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Dear Readers, 

We’re excited to bring you, in this issue, develops first Newton article. Even if you're 
not set up for Newton development, you may find this article of interest. But itis the 
article on zooming windows that inspired diis editorial. The subject is user interface 
annoyances: those cases w here the application doesn’t quite do what the user expects 
it to — as when a window zooms to an odd location — and the user has to adjust for 
it. So what’s the big deal? Well, it all adds up. Over time, the harm to the user from 
compensating for these problems can be physical as well as mental. You'll end up 
with a customer who is suffering in more ways than one. 

As Joan Stigliani puts it in her forthcoming book, High-Tech Health: The Computer 
User's Survival Guide : u Softw are can make you work hard and contribute to overuse if 
it requires a lot of mouse use — clicking and dragging, scrolling, moving the cursor 
back and forth across the screen — ora lot of complex key sequences or excessive 
keying. Software that is difficult or frustrating to use can increase stress and tension." 
This especially struck a chord with me, since I suffer from tendinitis caused by 
excessive keying and mousing. So Pm going to take advantage of this opportunity to 
vent my frustration (isn't that what editorials are for?). Mainly, I hope to have at least 
some small influence on how you design the interface for your applications in the 
future. 


Why do so many applications lack common sense? Why, for example, shouldn’t Print 
or Save work on my frontmost document even if the active window happens to be a 
dialog box? Why can’t 1 just type Command-!' followed by text to he found rather 
than first have to select the text that the application (for some odd reason) didn’t 
choose to highlight in the Find dialog? Why, even on my two-page monitor, do I 
have to resize a teeny window for every piece of e-mail I receive, or read a mere eight 
lines at a time, scrolling repeatedly (excessively) to get to the end? Why, when I cut a 
double-clicked word and then paste it, do so few applications add spaces intelligently? 

The list of user interface superfluities goes on and on; these are only the problems I 
encounter most frequently each day Please, give my hands (and my mind) a break! If 
I may make a few suggestions: 

* Don’t blindly follow what other applications have done: maybe 
they didn't think it through well enough* There’s a place for 
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barn it occupied a huge room in another 
building.] By the time computers were the size of 
terminals, Caroline was on her way to Apple to 
write Inside Macintosh. She digressed to spend 
five years at NeXT, where she managed the 


Publications group, but returned to the Apple fold 
to edit develop. Caroline owes her love of the 
printed word to her father, who worked for the 
New York Daily News for over 50 years. There 
was no greater thrill as a child than to go to the 
office with him and see the copy desks, 
darkrooms, printing presses — and, of course, the 
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guidelines and precedents, but don’t totally disregard common 
sense. 

* Use the application yourself for real tasks until you’re blue in the 
face. Be honest; what bugs you about it? Your users will be even 
Less tolerant. 

* Do extensive user testing before first ship, of course — but even 
after you ship, solicit feedback and incorporate it into the next 
release. Be sure to get feedback from experienced users, not just 
first-timers. 

■ Beware of creeping featnrisni: fix problems your testers or 
customers have with current features before adding new ones. 

These suggestions are based on my own experience as the user manual writer and 
ad hoc product manager for the first version of the WriteNow application. John 
Anderson, one of the authors of WriteNow, says he thinks interface problems stem 
from software being too hard to write (something his next product will address) and 
from the related problem of software teams being too large. With many specialized 
programmers on a project, no one person focuses on the overall picture well enough 
to make the requisite intelligent decisions about the interface. Given a large team, a 
good product manager can make all the difference in the world. Look for someone 
both knowledgeable about the market and able to grasp the technical issues. As I 
noted about technical writing in an earlier editorial, product management isn’t a job 
that just any smart person can do, or that CEOs or VPs should tackle in their spare 
time. 

So I guess the moral is that more is not always better — not when it comes to 
features in an application or programmers on a project, and certainly not when it 
comes to keystrokes and mouse clicks in an interface. Please, keep it dean. 



Caroline Rose 
Editor 
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FLOATING BUGS 

I liked Issue 15’s article on floating 
windows and have successfully 
implemented your routines, I did, 
however, find one bug. Your routine 
Hide Referenced Window can leave the 
process’s window list pointing to a 
deallocated window when there are no 

LETTERS floating windows. 

— Chester Murphy 

Thanks for pointing this out It's fixed — 
along with some other small bugs — in the 
code on this issues CD. (Its been fixed since 
Issue 16 s CD.) 

— Dean Yu 


problems using the header file with 
THINK C. Additionally , the new version of 
the floating windows code uses the universal 
header files that are discussed in the 
“Making the Leap to PowerPC ” ankle in 
Issue 16 and are on this issue's CD ♦ 

We recommend using Call Un i versa IProc in 
your source code (or one of its specific 
variants, like CallActivateHandlerProc in 
the floating windows code) to allow for 
greater portability of your source code 
between platforms. For a detailed 
explanation of using Call Un tv ersa IProc 
and UniversalProcPtrs, check out the 
aforementioned article in Issue 16. 

— Dean Yu 


PRAGMATIC SOLUTION 

Floating windows is one of my favorite 
subjects. I tried to compile your 
WindowExtension example, using 
THINK C 6.0. My first problem was 
with USES68KINLINES. THINK C 
checks the #pragma parameter with the 
function declaration. So I tried to use 
A1 and DO as parameters, but then I 
needed a few more #pragmas for the 
activate handlers. I still don’t have a 
working version. 

Also, could you explain why we need 
Cal I Universal Proc? Pm quite happy 
with the C syntax. 

Thank you very much for doing such a 
good job on die article. 

— Robert Puvol 

The use of USES 6 SKIN LINES has 
changed since Issue 15 went to press 
Currently, It pragma parameters arm 't 
used any more , so you should?? 7 have any 


DESKTOP FILES REDUX 

I liked Issue 15’s Puzzle Page, about the 
damaged desktop files. I’ve seen this 
bug often, since I fix a lot of damaged 
hard disks. 

You probably know this, but if the 
desktop files gel hosed in a certain way, 
rebuilding them in the Finder won't fix 
them. You have to delete diem (or 
rename them) to get the Finder to build 
new files from scratch, 

AutoDoubler comes with a hide utility 
called Desktop Reset just for deleting 
the desktop files, 

— David Shayer 

/ didn't know this when I wrote that Puzzle 
Page , but you're right. When the desktop 
file gets damaged to the point where the File 
Manager can't open it , the Finder can't 
rebuild the file , so you have to throw it 
away or rename it. 

Thanks for the feedback. 

— Konstantin Othme?' 
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IF MORE OF YOU DON'T WRITE, WE'LL 
HAVE TO START MAKING THEM UP! 

We welcome timely letters to the editors, 
especially From readers reacting to articles that 
we publish in develop . Letters should be 
addressed to Caroline Rose (or, if technical 
deve/op-re I a ted questions, to Dave Johnson] at 
Apple Computer, Inc,, 20525 Manani Avenue, 
M/S 3G3-4DP, Cupertino, CA 95014 (AppleLink 


CROSE or JOHNSON,DK], All letters should 
include your name and company name as well 
as your address and phone number. Letters may 
be excerpted or edited For clarity (or to make 
them soy what we wish they did).* 
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USING PROTO 


TEMPLATES 
ON THE 
NEWTON 



HARRY R. CHESLEY 


Proto templates are a central feature of the Newton development 
environment . All Newton applications use built-in prototypes^ and 
developers can also write their own application-specific prototypes . This 
ankle uses proto templates in the design of an application that plays a 
few simple games . For non-Newton developers it reveals some of the 
flavor of designing and writing Newton applications . 


An application often includes multiple instances of a design element, with only minor 
variations among them* In object-oriented systems, iris possible to share die common 
portions of the design among several different pieces of the application by using 
inheritance* On the Newton, you can do this with proto templates, which let you reuse 
the definition of a particular type of view very efficiently* Since views are the basic 
visual and functional elements of the Newton user interlace, proto templates give you 
a very powerful ability to share and reuse user interface features. 

Built-in proto templates supply most of the common view r s seen in Newton 
applications — push buttons, pop-up menus, checkboxes, radio buttons, and so on. 

In addition, developers of Newton applications can define their own proto templates* 
These templates allow for very compact designs, shorter development times, easier 
maintenance, and smaller finished applications* 

In this article we develop a game application for the Newton called TapBoard* 
TapBoard is actually three games, each with its own style of board, rules of play, and 
algorithm for computer-generated moves. The games have many elements in 
common, and these can be abstracted into a proto template containing the shared 
aspects of the design. You’ll find much of the code for TapBoard in the article’ the 
complete source code can be found on this issued CD. 

If you’ve never written a Newton application, see “(Slightly) Inside Newton 
Programming” tor an introduction to the development process and some of the 
Newton terminology that’s used in this article. 


HARRY R, CHESLEY (AppleLink CHESLEY 1 ( 
MewtonMail CHESLEY) has spent most of the lost 
three years in subspoce (see develop Issue 7, 

'The Subs pace Manager in System 7.0"] working 
on PowerTalk templates. His return to Earth-normal 
space was accompanied by an interstitial stutter, 
resulting in a temporary doubling of his 
personality matrix. This allowed him to 
simultaneously finish PowerTalk and design and 


write the NewtonScript communications interface 
(proto End points). He's better now, but still 
occasionally repeats himself in social situations. If 
he should happen to tell you a story you've heard 
from him before, just humor him and pretend it's 
all new stuff. Too much self-referential 
introspection could cause a subsfitial relapse/ 
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(SLIGHTLY) INSIDE NEWTON PROGRAMMING 

BY GREGG WILLIAMS 


Programming the Newton is different — and ! mean 
that in a good sense. Once you digest the Newton 
documentation, you can create a simple application and 
have it running on a Newton in about 15 minutes. The 
Newton development process encourages lots of quick 
code/compile/debug cycles — good for those of us who 
need positive reinforcement on a regular basis — and the 
cycle is short enough that you don't notice a delay. 

OVERVIEW 

Before I describe how a Newton program works, here's 
an overview of the development process. To create □ 
Newton application, all you need is the Newton Toolkit 
(available from APDA), o serial cable, a 68030 
Macintosh with 8 MB of memory and 3 2-bit addressing, 
and a Newton, You create your program with the Toolkit, 
compile it, and then download it to a Newton that's 
connected to your Macintosh through a serial port. Your 
completed application appears in the Extras drawer, just 
like any other third-party Newton application. 

Using tools from a floating window called the layout 
palette , you draw the layout of your application — what 
its screens should look like -— in layout windows. Not only 
can you reuse the dozens of user interface definitions that 
the Newton Toolkit supplies, you can create your own 
custom proto templates (more on proto templates below). 
Each layout or custom proto template is stored as a 
separate file; all of these files, plus optional files that 
contain the Macintosh-style resources your program 
needs, are grouped into what's called a project. 

Once you've drawn all your views, you can open a 
browser window (familiar to users of object-oriented 
languages like Smalltalk and LISP). In the browser 
window, you can add and modify both code and data 
associated with the objects in your program. The code 
you write is in a new language called NewtonScript , 
which is a simple but sophisticated symbolic language 
with a Pascal-like syntax. 


Most of the [usually short) routines you'll write execute 
when triggered by a user action, like the user's tapping a 
button or writing in a designated area, or by a system 
action. You're already acquainted with this event-driven 
approach from your experience in programming for the 
Macintosh, And if you've been doing object-oriented 
programming, the idea of a network of cooperating 
software objects, rather than a hierarchy of routines 
executed by a processor that's always in control, is also 
familiar to you. 

FRAMES AND SLOTS 

One idea you may not be familiar with, depending on 
whether you've used object-oriented languages, is that of 
frames. Artificial intelligence fanatics will probably kill 
me, but I think of o frame as just a record of data, and 
s/ofs as what most of us call record fields. However, slots 
in NewtonScript are more versatile than record fields in 
several ways. First, slots aren't limited to one type of data. 
(Like Newton variables, slots aren't typed and can hold, 
for example, an integer one minute and a frame the next) 
Second, you can arbitrarily add or remove slots from a 
frame at any time, including during program execution. 
Third, you con access slots indirectly through path 
expressions ; these allow you to store part of a slot's 
pathname in a variable, thus letting the contents of a 
variable determine which slot gets accessed. In 
NewtonScript, a frame looks like this: 

{ slotnamel: value!, slotname2: value2, 
slotnaineN; valueN } 

Slot names can be omitted or mentioned in any order. By 
using the slot names _proto and ^parent, you can create 
data structures that exhibit Newton's flavor of object- 
oriented behavior, as discussed later in this article. 

To access the data in a frame's slot, you use the notation 

framename.elotname 
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TEMPLATES, VIEWS, AND PROTOS 

Everything you see on the Newton screen is composed of 
views. A view can display, among other things, a picture, 
a paragraph of text, an area for writing or drawing, an 
on-screen keyboard, a calendar-month page, a pop-up 
list, or a gauge (which is like a horizontai thermometer). 

Many of the things that you see on the screen are 
standard prefabricated user interface elements built into 
the Newton ROM and available to every Newton 
developer* These are colled proto templates , or protos for 
short, and they include six different kinds of buttons and 
checkboxes, protoSliders (like a linear slider light switch), 
pratoRolls (which allow information to scroll vertically off 
the screen), and different kinds of labels, borders, and 
standard interface elements* Each tool on the Newton 
Toolkit layout palette allows you to lay out a view or a 
proto. 

Views can contain views inside them, and in fact, a proto 
is a predefined hierarchical grouping of views that 
behaves in a certain way. You can create your own 
custom protos by drawing them in layout windows. 

In Newton Script, you can describe a view as a frame 
called a template; the Newton later creates a view from 
the template at run time. The slots in a template represent 
the view's data and the functions that implement the 
behavior you have to add, (Most views and protos have 
behavior built in, and the built-in behavior of a proto is 
often quite extensive.) When your application executes, a 
template (which cannot be changed) is used to create the 
data structure in RAM that corresponds to the visual 
representation of the view — that is, what you see on the 
Newton's screen. 

To send a message to a view (that is, to invoke one of its 
methods), the syntax is 

viewsmessagename(argl, arg2, . argN) 

(The function involved is the method, while the name used 
to invoke it is the message. You send a message to an 


object, and that causes the associated method to 
execute.) 

SYSTEM MESSAGES 

As with the Macintosh, Newton applications are driven 
by user events — the user taps or draws on the Newton 
screen in different places — as well as by system events. 
The Newton sends your program system messages , which 
trigger their corresponding methods. In some cases, you 
let the built-in Newton methods do their work; in many 
others, you write your own. There are 25 or so system 
messages you need to know about. Here are a few of 
them, and when the corresponding methods execute; 

* viewChangedScript: executes when a view slot is 
changed using the SetValue function or when certain 
functions change a view directly 

* viewDrawScript: executes when a view needs to be 
drawn 

* viewStrokeScript: executes when a user writes inside 
a view 

* viewSetupFormScript, viewSetupChildrenScript, 
viewSetupDoneScript: execute at specific points 
during the setup of a view, before the view is 
displayed 

* vfewJdleScript: executes periodically 

* viewGuitScript: executes just before a view is 
disposed of 

Some system messages pertain to particular views — for 
example, buttonClickScript (for buttons), key Press Script 
(for keyboard views), and monthChangedScript (for the 
monthly calendar view). 

AND THAT'S JUST THE BEGINNING. , . 

There's a lot more to programming the Newton. You can 
find out more by reading the manuals that come with the 
Newton Toolkit. Be sure to read any errata sheets, release 
notes, and "read me'' files; I overlooked one and missed 
a piece of information that would have saved me several 
days' work! 


For more information about views, see the 

"Views" chapter of the Newton Programmer's 
Guide, • 
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GAMES WE'RE GOING TO PLAY 

TapBoard plays three games- Tic-tac-toe, Gomoku, and Reversi. The user chooses 
one of the games from a set of radio buttons, a game board is displayed, and the 
user moves by tapping a square on the board. The application responds with a 
countermove. This process repeats until one player wins or the game ends in a tie. 
When the user closes TapBoard, the application remembers the state of the board — 
which game is being played, where the pieces are placed, whose turn it is, and the 
game’s outcome. When TapBoard is reopened, it restores the state so that the user 
ean continue the game where it left off. 

So, common elements shared by the games include the following: 

* displaying the board to the user 

* adding a new move to the board display 

* acknowledging the users tap with an appropriate sound 

* tracking the stroke to decide w hether it ended on the same square 
as it started on 

* figuring out which square it w as, and w hether the move is valid 

* recording the move 

* checking it to see if it’s a winning or tying move 

* uncovering a good move when it’s TapBoard’s turn 

* saving the state of the board w hen die user closes the game 

* restoring the state w hen die game is reopened 

All these common actions can be abstracted into a prototype that each specific game 
can then inherit from (as described later in the section “The protoBoard Proto 
Template”). But since die games arc different, each also has its own rules and possibly 
its own board, and each requires its own algorithm for finding good moves for the 
computerj details follow. 

TIC-TAC-TOE 

You undoubtedly know this game, but we’ll describe it briefly: Tic-tac-toe is played 
on a 3 x 3 board with players taking turns making X 5 s and O’s. The first player to get 
three in a row r horizontally, vertically, or diagonally wins. If neither player gets three 
in a row', the game is tied. Figure 1 shows a typical game of Tic-tac-toe. X gets three 
on the diagonal and wins. 

Tic-tac-toe is a simple game to master. There are a few' easy heuristics, such as always 
take the center square if you can, and with a littie di ought ids not hard to see several 
moves ahead. 
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Figure 1 

Tic-tac-toe 

Tap Board's algorithm for determining a good Tic-tac-toe move involves doing a two- 
move look-ahead, combined with some simple heuristics. The look-ahead tries all 
possible moves, then tries all possible answering moves. The heuristic gives greater 
weight to taking the center and corner squares. This algorithm doesn't play a perfect 
game of Tic-tac-toe, but this is actually an advantage, for two reasons: it pulls players 
into the game by giving the impression that the computer is an easy target, and it 
provides a game that's playable by younger users (my five-year-old daughter loves it), 

GOMOKU 

Gomoku is played on an 8 x 8 board. Players take turns placing pieces on the board, 
and the first player to get five in a row horizontally, vertically, or diagonally wins. 
Figure 2 shows a short game of Gomoku won by white {a real game would of course 
be played more defensively than this one, which is for demonstration purposes 
only). 



Figure 2 

Gomoku 


Gomoku is more challenging than Tic-tac-toe. The larger game board and longer 
winning sequence make for many more combinations, and the game virtually requires 
that the winner “sneak up” on the loser, rather than just going for a simple sequence 
of five pieces, which the opponent can easily detect and prevent. 

TapBoard’s approach to finding a good Gomoku move involves making three passes 
over the board: the first looks for winning moves; the second looks for situations 
where the user has three or more in a row and tries to block those; the third looks for 
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situations where TapBoard has three or more in a row and tries to add to those. This 
algorithm plays a defensive game that's hard to beat, 

REVERSI 

Reversi is also played on an 8 x 8 board. Four pieces are placed in the center of the 
board as shown in Figure 3A, and the players take turns placing pieces, trying to trap 
the opponent's pieces between the new piece and an existing one horizontally, 
vertically or diagonally Figure 3B shows one of the squares that would be a legal first 
move for white. The pieces that are “trapped” change color, or reverse — hence the 
name of the game, Figure 3C show's the result of die move in 3B, 
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Figure 3 

Reversi 


Play continues until no legal moves are left. The player with the most pieces wins. If 
both players have the same number of pieces, it's a tie. Because of the reversing 
pieces, the situation can change suddenly and dramatically. Often one player looks 
like the clear winner until near die end of the game, w hen the other player suddenly 
surges ahead and wins, 

TapBoard looks for a good move in Reversi by checking every possible move, 
counting the number of user pieces that will be converted, and then modifying the 
counts based on heuristics concerning plays along the edges of the board. This 
algorithm plays the game quite well, and can often come on surprisingly strong at the 
end of the game, 

THE TAPBOARD APPLICATION 

The layout of the TapBoard application is shown in Figure 4, The center of the 
screen is the game board, and there are three different game board templates 
corresponding to the three games. Only one is displayed at a time. Below the board 
are radio buttons indicating w hose turn it is. Underneath these are pictures of the 
pieces for the user and tor the application, w hich change from game to game. Below 
them is a set of radio buttons with the names of the games, from which the user 
chooses. At the bottom of the screen is a set of buttons including a time and battery 
status button, buttons for New Game, Help, and Credits, and a dose box. 
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Figure 4 

TapBoard Application Screen Layout 


Besides the games themselves, the application has to take care of the following: 

* selecting which game to play 

* showing whose turn it is, and letting the user choose who goes first 

* displaying help and credits 

* triggering save and restore operations when the application closes 
and reopens 

* removing the saved state from memory when the application is 
removed from the Newton 

Most of the TapBoard application is in the application template and the game boards. 
The buttons are in the application template. The core functionality of the application, 
playing the games, is in the game boards and in protoBoard, the proto template from 
which all three games inherit. (Newton inheritance is a little different from w r hat you 
might be used to; for more information, see “Proto and Parent Inheritance.”) 

THE PROTOBOARD PROTO TEMPLATE 

The protoBoard proto template takes care of several functional areas. In some cases, 
it does everything needed by the game hoards that derive from it. In other cases, one 
or more of the game hoards must override part of the proto template functionality — 
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PROTO AND PARENT INHERITANCE 

When you draw a view inside another view, the one 
inside is said to be a subview or a child view . When you 
draw nested views in a layout window in the Newton 
Toolkit, you're doing the equivalent of writing code that is 
a frame, with each piece of data or method having its 
own slot. 

Unless it's at the end of its chain, every view has a _proto 
slot, which points to the proto From which it inherits its 
behavior. Similarly, every view (except the "top" one) has 
o ^parent slot, which points to the view that contains it 
[that is, its parent view], 

Here's where things get interesting, A view exists in RAM 
while your program is executing; it can have its own slots, 
which are also in RAM. If some code tries to access a slot 
that the view doesn't have, the view looks for that slot in 
the view's proto. If its proto doesn't have that slot, the 
proto looks for the slot In the proto's proto (if it has one), 
and so on up the line of proto ''ancestors.'' The value 
that's ultimately returned is used as if it were actually a 
slat in RAM belonging ta that view. 

But wait — there's morel You also have parent 
inheritance: a view can get a slot value from one of its 
parent views. If the desired slot isn't Found in any proto, 
the search continues (from above) with the view's parent 
and, if necessary, its protos, (The process is a bit different 
when changing slot values; the only slot values you can 
change are in the view or one of its ancestors — all of 
these slots, of course, are in RAM. For details, see the 
"Working With Proto Templates" chapter of the 
NewtonScript Programming Language manual.) 


Why two kinds of inheritance? Two answers: ROM and 
application size. The reason for views and protos in the 
first place is to minimize the amount of code in your 
application and so make it as compact a$ possible. 
Because views and protos are in ROM, though, you can't 
change their slots. You need another mechanism to 
override their default values, and that's where proto 
inheritance comes in. 

Proto inheritance shrinks application size by minimizing 
the amount of code associated with individual instances 
of often-used "building blocks." Parent inheritance shrinks 
application size by allowing related elements in your 
program to share common data or behavior. [For 
example, three radio buttons in a duster may share a 
button-click method that's different from that of other 
buttons on the same screen.) 

In addition to sending a message to a certain view, you 
can send a message that starts with the current view and 
checks protos, parents, and parent protos until it finds a 
view or proto template that has a slot with the same name 
as the message. The associated method, wherever it 
comes from, is then applied to the current view. The 
syntax is 

:messagename(argl, arg2, argN) 

This is a very brief overview of a software architecture 
that has many implications. To fill in the gaps, read the 
Newton documentation. 

— GW 


and several slots are designed to lie overridden. In still other cases, a protoBoard 
function uses data slots defined in the game boards as input. 

BOARD STATE AND SHAPE 

The protoBoard proto template maintains a two-dimensional array, named 
boardArrav, that remembers where pieces have been placed on the board. The array 
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is actually one entry larger than the board in each direction. This oversizing can be 
handy in die algorithms used to find a good move for the application. 

Each space in the array can have one of four values: empty, Newton piece, user piece, 
or edge of the board. To simplify the algorithms used to compute the application's 
moves, we use I for the user and -1 for the Newton, so that if p is a piece of one type, 
-p is the opposing type of piece. Empty spaces are filled with nil, and board edges are 
(1 — neither ml nor a valid Newton or user piece value. These same values are used to 
keep track of whose turn it is and who has won (if anyone). We define constants for 
each of these potential values: 

constant kEmptySquare ;= nil; 
constant kNewtonPiece -1; 
constant kUserPiece := 1; 

constant kBoardEdge ;= 0; 

constant kTieWinner := 0; 

Here's the portion of protoBoard’s viewSetupFormScript diat creates board Array: 

protoBoard.viewSetupFonaScript := func() 
begin 

// Make the board array; we make it one entry larger in each direction 
// than the board r which is nice sometimes when figuring out moves. 
boardArray := Array(squaresWide+2, kEmptySquare); 
local i; 

for i ;= 0 to squaresWide+1 do 
begin 

boardArray[ij ;= Array(squaresHigh+2, 

if (i = 0) or (i = squaresWide+1) then 
kBoardEdge else kEmptySquare); 
boardArray[i][0] t = kBoardEdge; 
boardArray[i]f squaresHigh+1] := kBoardEdge; 
end; 

// Reset the number of squares left. 
squaresLeft := squaresWide * squaresHigh; 

// No winner yet. 
winner nil; 

//Do any game-specific setup. 

;setupBoard(); 


end 

We initialize squaresLeft to the number of squares on the board so rhat TapBoard can 
determine whether the board is full without having to check every square. We also set 
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winner to nil. When the game is finished, the winner slot is set to kUserPiece (user 
won), kNewtonPiece (Newton won), or kTieWinner (tie). This allows for a very 
quick check on whether the game is over and who won. 

The setupBoard function is called to do any game-specific hoard setup. For example, 
Reversi needs to place four initial pieces on the board. The default setupBoard 
function defined in protoBoard does nothing; inheritors of protoBoard override it as 
needed. 

"Two slots, squares Wide and squaresHigh, must be defined by any protoBoard 
inheritor to determine the width and height of the board. They're used throughout 
protoBoard — as in viewSempFormScript — and in the following utility functions. 
(Note that LocalBox is a function that returns a rectangle having the width and 
height of the view in its right and bottom slots, respectively.) 

// The height of a square: 
protoBoard.sguareHeight := func() 
begin 

return :LocalBox{).bottom div squaresHigh; 

end 

// The width of a square: 
protoBoard.squarewidth := func() 
begin 

return ;LocalBox()-right div squareswide; 

end 

// The bounds of a square: 
protoBoard.squareBounds := func(x, y) 
begin 

local width :squareWidth(); 
local height :» :squareHeight(); 

// RelBounds takes a top and left coordinate, a width, and a height 
// and returns a rectangle. 

return RelBounds((x-1)*width+l, (y-1)*height+l, width-1, height-!); 

end 

// Which square (1..squareswide) contains coordinate x (or Eero if none); 

protoBoard.squareOfX := func(x) 

begin 

local gb := :GlobalBox(); 

if (x < gb.left) or (x > gb.right) then return 0; 
else return ((x - gb.left) div :squareWidth()) + 1; 

end 
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// Which square (1..squaresHigh) contains coordinate y (or zero if none): 

protoBoard.squareOfY ;= func(y) 

begin 

local gb := :GlobalBox(); 

if (y < gb.top) or (y > gb*bottom) then return 0; 
else return {(y - gb.top) div :squareHeight()) + 1; 

end 

DRAWING THE BOARD 

The drawing of the board itself is created once and stored in the slot 
background Drawing. This drawing is then displayed by viewDrawScript. 

protoBoard.viewDrawScript := func() 
begin 

:DrawS hape(backgroundDrawing, nil); 

end 

The backgroundDrawing slot is built in view Setup Done Script, which is called just 
before the view is shown on the screen. The default function supplied in protoBoard 
draws a closed set of squares for die board. This is appropriate for Gotnoku and 
Reversi but is overridden by Tic-tac-toe, which needs an open grid. 

protoBoard.viewSetupDoneScript := func() 
begin 

// Build the board display. This builds a closed set of squares, 

// but can be overridden, 
local height := :LocalBox().bottom - 1; 
local width := :LocalBox().right - 1; 
backgroundDrawing := []; // Empty array 

for x := 0 to width by isquareWidth() do 

AddArraySlot(backgroundDrawing, MakeLine(x, 0, x, height)); 
for y := 0 to height by :squareHeight() do 

AddArraySlot{backgroundDrawing, MakeLine(G, y, width, y)); 

end 

ADDING PIECES 

Besides an entry in boardArray, each piece has a subview within the board of class 
clPictureView, which displays the piece on the board. Adding a piece to boardArray, 
adding the corresponding sub view, and adjusting squaresLeft are the responsibility of 
the addPiece function. 

protoBoard.addPiece func(p, x, y) 

begin 

// Mark the new piece in boardArray. 
boardArray!x][y] := p; 
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// Check if there's already a view there in the view list, 
local bounds ;= :squareSounds(x, y)? 

local i := if p = kUserPiece then playerlPiece else player2Piece; 
local v; 

// ChildViewFrames returns an array containing all child views, 
foreach v in :ChildViewFrames() do 

if (v.viewBounds.top = bounds.top) and 

(v.viewBounds.left = bounds.left) then 
begin 

// If there is, replace the icon and redisplay. 

SetValue(v, 'icon, i); 
return; 
end; 

// One less square available, 
squaresLeft i- squaresLeft - 1; 

// Create, add in, and display the new view. 

AddstepView(self, 

{viewClass; clPictureView, viewBounds: :squareBounds(x, y), 
viewFlags: Wisible, icon; i});Dirty(); 

end 

To determine the picture to display, addPiece looks in slots player 1 Piece and 
player2Piece, which contain pictures for the user and for the computer. The default 
versions supplied in protoBoard are suitable for Reversi and Gomoku. Tic-tac-toe 
overrides these slots to provide an X and an O. 

Note that this function checks to see if there’s already a piece on that square. If there 
is, it simply changes the picture for the piece rather than creating a new view. In most 
games, moving on a square that already has a piece on it is illegal. But in Reversi, we 
often replace existing pieces with pieces of the opposite color. 

MAKING MOVES 

Checking the legality of a move, deciding whether it’s a winning or losing move, and 
then switching the state of whose turn it is, are done in the move function. This is the 
function to call to actually make a move. 

protoBoard.move := funcfp, x, y) 
begin 

// Check if this is a reasonable thing to do. 
if :isTurn(p) and ;validMove(p, x, y) then 
begin 

U Add the piece to the board. 

:addPiece(p, x, y); 
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// If this was a winner, let the user know, 
if :winningMove(p, x, y) then 
begin 

winner p; 

:announceWin(p); 

end 

//if this was a tie-maker, let the user know, 
else if :tieGame() then 
begin 

winner : = kTieWinner; 

:turn(kTieWinner); 

:announceWin(kTieWinner); 

end 

// Switch whose turn it is. 
else :turn(-p); 
end; 

end 

The functions isTurn, announceWin, and turn are global application functions 
defined in the application template; well get to them later The functions validMove, 
winnmgMove, and tieGame are game-specific and are defined in the protoBoard 
inheritors. We provide default versions: 

protoBoard.validMove := funcfp, x, y) 
begin 

// If it's an empty space, it's legal to move there. 

// This function may be overridden, 
return boardArray[x][y] = kEmptySquare; 

end 

protoBoard.wlnningMove := func(p, x, y) 
begin 

//By default, the computer never wins and the user wins when the 
// board is full. This is always overridden, but we leave it in 
// because it can be handy during the early stages of developing 
// a new game. 

if p = kNewtonPiece then return nil 
else return squaresLeft = 0; 
end 

protoBoard.tieGame := func{) 
begin 

// It's a tie if there's nothing left to do. This can be overridden, 
return squaresLeft = 0; 

end 
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THE USER'S MOVES 

The user moves by tapping on rhe board. When the tap first occurs, viewClickScript 
is called. This function turns off ink and plays a sound to let the user know clearly 
that the tap was hard enough. The actual move is recorded in viewStrokeScript, 
which is called after die user lifts the pen from the screen, 

protoBoard.viewClickScript := fune(unit) 
begin 

//No ink (we're tapping, net drawing}. 

InkOff(unit); 

// Make a nice little click to give the user warm fuzzies. 
PlaySound(ROM_click); 

// But let the normal processing handle tracking and such, 
return nil; 

end 

protoBoard.viewStrokeScript : = func(unit) 
begin 

// Find out where we clicked to start with. 

local originalX := tsquareOfX(GetPoint(firstX, unit)); 

local originalY := :squareOfY(GetPoint(firstY, unit)); 

// If we ended where we started, make the move, 
if (originalX <> 0) and (originalY <> 0) and 

(originalX = :squareOfX(GetPoint(finalX, unit))) and 
(originalY - ;squareOfY(GetPoint(finalY, unit))) then 
;move{kUserPieee, originalX, originalY); 
return true; 

end 

We return nil from viewClickScript to say we didn’t handle it, so die system processes 
the stroke for us. But we return true from viewStrokeScript because here we did 
handle the stroke and don’t want the system to do anything more. 

THE COMPUTER'S MOVES 

It’s the computer’s turn to move after the user has moved, or because the user tapped 
the Computer’s Move radio button. Rather than put code in each of these places, we 
simply set up an idle method called viewIdleSeript in protoBoard that checks to see if 
ids die computer’s turn and then makes its move. 

This is not the most efficient approach because it involves checking periodically while 
the user is thinking, but it’s quite simple (and shows how to set up idle methods). 
Since it only checks every quarter of a second, it doesn’t actually use much CPU or 
battery power 
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protoBoard.viewSetupFormScript func() 

begin 

// Have our idle method called. 

;SetUpidle(250); 
end 

protoBoard.viewIdleScript := func() 
begin 

// If we are visible, and it's the computer's turn, and there's no 
// winner... 

if Visible[self) and :isTurn)kNewtonPiece) and (winner = nil) then 
begin 

// Put up the 11 Working..." display, and figure the computer's 
// move. 

;startWorking(); 

:makeComputerMove(); 

:stopworking(); 

end; 

// Try again in a quarter of a second, 
return 250? 

end 

protoBoard.makeComputerMove := func() 
begin 

//By default, we just do something random. 

// This is always overridden. 

;makeRandomMove(kHewtonPiece); 
end 

protoBoard.makeRandomMove ;= func(p) 
begin 

// Try ten times to find a reasonable random move, 
local i, x, y; 
for i := 1 to 10 do 
begin 

x Random(l, squaresWide); 

y Random(l, squaresHigh); 

if :validMove(p, x, y) then 
begin 

:move(p, x, y); 
return; 
end; 

end; 
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// if that doesn't work, just pick the first linear move, 
for x := 1 to sqnaresWide do 
for y := 1 to squaresHigh do 
if :validMove(p, x, y) then 
begin 

:move(p, x, y); 
return; 
end; 

end 

SAVING AND RESTORING STATE 

Between invocations of TapBoard the application needs to save its state, so that it can 
restore the state when the user reopens die application* Permanent data on the 
Newton is stored in one or more database-like objects called soups (for more on soups 
and related concepts, see “Soups”)* Since w r e only need to save a fairly simple set of 
state information, we can put it into the system configuration and preferences soup. 
This soup is named “System” and contains information such as the user’s name and 
Newton configuration options. 


SOUPS 

If frames are sari of like records, then soups are like what 
we normally think of as files — both hold collections of 
data. But soups — like frames — do so In a way that's 
more relaxed and free form. To use a food analogy if 
traditional files are like a stack of sugar cubes, then soups 
are like, well, soup. 

Soups store data in a general format that doesn't limit 
their usefulness to the application that created them. For 
example, any Newton application can access all the 
names in the Newton's built-in address book because the 
names are in the same soup. 

Soups engender their own terminology. Here are a few 
terms you need to know: 

* Entry: An entry points to a "record'' of data. When an 
entry is accessed as a frame, the actual data is 
constructed in RAM and stays there until it's no longer 
referenced. 


* Store: A store is a place where data physically resides. 
The Newton has a single built-in store, which is in 
RAM; an installed PCMCIA RAM or ROM card would 
be another store. 

* Query: To retrieve an entry from a soup, you perform 
a query on it. This returns a cursor that represents the 
criteria specified by the query. 

* Cursor: A cursor [also called o cursor object] points to 
the First entry that matches the query. To read other 
matching entries, you send the cursor Next and Prev 
(previous) messages, which 'move" the cursor to point 
to other matching entries. Cursors are dynamic, that is, 
they find the next entry in the soup as it exists when the 
cursor is moved. 

Soups ore one of the uniquely new things about the 
Newton, and are a topic unto themselves. To learn more, 
see the documentation that comes with the Newton Toolkit. 

— GW 
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The process of saving Lind restoring the state is triggered in the application view, as 
we’II discuss later. But the bulk of the actual work is done in protoBoard, 

protoBoard.saveState ;= func() 
begin 

// Get the existing state entry, if any. 
local stateEntry := :getStateEntry()? 
it If there isn't one yet, make one. 

// Notes GetStores{)[0] returns the built-in store? 

// GetSoup{ROM_SystemSoupName) returns the "System" soup, 
if stateEntry = nil then 

stateEntry :- GetStores()[0]:GetSoup(ROM_SystemSoupName) 

:Add({Tag: kPackageName}); 

// If we can't make one, well, uh, let's just forget the whole thing, 
if stateEntry - nil then return; 

// Build an array of pieces and their positions from boardArray. 
local x, y; 
local pieces ;= []; 
local ba := boardArray? 
for x ;= 1 to squaresWide do 
for y ;= 1 to squaresHigh do 

if ba[x][y]l <> kEmptySquare then 

AddArraySlot(pieces, {player: ba[x][y], x: x, y: y} }? 

// Remember which game this is, the piece positions, whose turn it is, 

// and the winner. 

stateEntry.name :- name; 

stateEntry.pieces := pieces ? 

stateEntry.whichTurn :whoseTurn(); 

stateEntry.winner winner? 

// Tell the soup to save the changed entry. 

EntryChange(stateEntry); 

end 

protoBoard.restoreState := func(stateEntry) 
begin 

// For each piece stored in the state entry, add it to the board, 
local p? 

foreach p in stateEntry.pieces do 
saddPiecefp.player, p.x, p.y); 

// Set whose turn it is. 

:turn(stateEntry.whichTurn); 

// Set the winner, if there is one. 
winner := stateEntry.winner; 
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The constant kPackageName is the name of the application concatenated with a 
registered signature. This string is unique, ensuring that we don’t try to use an entry 
in the soup that is already used by another application: 

// who we are: 

constant kAppSymbol := 1 |TapBoard:Chesley|; 
constant kPackageName "TapBoardrChesley "; 

The function getStateEntry is defined in the application template: 

TapBoard.getstateEntry := fune() 
begin 

// Find our one-and-only entry in the System soup, if there is one, 
return Query(GetStores()[0]:GetSoup(ROM_SystemSoupName), 

{type: 'index, indexPath: 'tag, startKey: kPackageName, 
validTest: func(item) StrEqualfitem.tag, 
kPackageName)}}:Entry(); 
end 

LET THE GAMES BEGIN 

Each game inherits from protoBoard all of the functionality described in the previous 
section. Now we only need to define die details of the game — the size of the playing 
board, what the pieces look like, what the valid moves are, and the algorithm for 
figuring out the computer's moves. 

TIC-TAC-TOI 

For Tic-tac-toe, we provide the name of die game and the board size and override 
the default piece pictures as follows: 

tictactoe := { ... name: "Tic-tac-toe", squaresWide: 3, squaresHigh: 3, 
playerIPiece: TapBoard.rsrc:XPicture, 
player2Piece: TapBoard*rsrclOPicture > 

We override the board drawing in viewSetupDoneScript. 

tictactoe.viewSetupDoneScript := func() 
begin 

// Hake an open cross-hatch (the default function does a closed board). 

local height := ;LocalBox[).bottom - I; 

local width := :LocalBox().right - 1; 

local xlncr ;= ;squareWidth(); 

local ylncr := :squareHeight{); 

backgroundDrawing := []; 
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for x := xlncr to width - xlncr by xlncr do 

AddArraySlot(backgroundDrawing, MakeLine(x, 0, x, height)); 
for y := ylncr to height - ylncr by ylncr do 

AddArraySlot(backgrounderawing, MakeLine(0 r y f width, y)); 

end 


We can use the default tieGame function, which says the game is a tie if all the 
squares are used, but we need to override winningMove. 


tictactoe.winningMove ;= func(p, x, y) 
begin 

local ba := boardArray? 
return 

((ba[x][1] = p} and (ba[x][2J = p> and (ba[x][3] 

((ba[1][y] = p) and fba[2][y] = p) and (ba[3]|y] 

{(ba[1I(1] = p) and (ba[2][2] = p) and (ba[3][3] 

((ba[3][l] - p) and (ba[2][2] = p) and (ba[l][3] 

end 


P>> or 
Pi) or 
Pi) or 
P)>? 


We also need to override makeComputerMove: 


tictactoe.makeComputerMove ;= func() 
begin 

local moves : = []; 
local bestScore -1000? 
local newScore; 
local x, y? 

// Try each board position, 
for x := 1 to squaresWide do 
for y := 1 to squaresHigh do 

if boardArray[x][y] = kEmptySquare then 
begin 

// Look ahead to score this move. 

newScore := :tryMove(kUserPiece, kNewtonPiece, x, y); 
//If this is the best one yet, remember only it. 
if newScore > bestScore then 
begin 

moves := []; 
bestScore := newScore; 
end; 

// If it's tied for best move, remember it too. 
if newScore = bestScore then 

AddArray51ot(moves, {mvx: x, mvy; y})? 

end; 
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// If there are any good moves... 
if Length(moves) > 0 then 
begin 

// Make the move, 

local move := moves[Random(0, Length(moves}-l)]; 
:move(kNewtonPiece, move.mvx, move.mvy); 

end 

// If there are no good moves, make a random one and pray, 
else :makeRandomMove(kNewtonPiece); 


tictactoe.tryMove func(d, p, x, y) 
begin 

// First, guess based on heuristics. 

// Mote: We use a quoted array here to save execution time; quoting 
// it means there will be only one copy — without the quote a new 
// one would be constructed each time at run time. Of course, this 
// also means we can't change the contents, but we don't want to. 
local score := '[5, 0, 5, 5, 10, 5, 5, 0, 5][x+x+x+y-4]; 

tt Make the move internally (we'll retract it later), 
local ba : = boardArray; 
ba{x][y] := p; 

squaresLeft squaresLeft - 1; 

it If it’s a winner, great, give it a high score. 

if :winningMove(p, x, y} then score := 100; 

// if there's anything to look ahead to, do it. 
else if (squaresLeft <> 0) and (d > 0) then 
begin 

local worstResponse ;= 1000; 
local newResponse; 
local x2, y2; 

// Try every board position, 
for x2 :- 1 to squaresWide do 
for y2 := 1 to squaresHigh do 

if ba[x2][y2] - kEmptySquare then 
begin 

// How good is this one? 
newResponse :- :tryMove(d~l, -p r x2, y2J; 
it If it’s a loser, give up quick, 
if newResponse >= 100 then 
begin 

ba[x][y] := nil; 
squaresLeft : = squaresLeft + 1; 
return -100; 
end; 
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// If it's the least bad one so far, remember that, 
if newResponse < worstResponse then 
worstResponse := newResponse; 

end; 

score ; = score - worstResponse; 
end; 

U Retract the move. 
bajx][y] := kEmptySquare; 
squaresLeft ;= squaresLeft + 1; 
return score; 

end 

That^ it. As you can see, most of the real work was done by protoBoard. 

GOMOKU 

For Goinoku, we provide the name and board size but leave the default piece pictures 
and board drawing. 

gomoku : = { ... name: "Gomoku", squaresWide: 8, squaresHigh: 8 ... > 

The ticGame function in protoBoard is fine, but winningMove needs to be 
overridden. We also need to override makeComputerMove anti make Ran dom Move 
(which makeComputerMove calls) because die default version makes some really 
stupid moves in the case of Gomoku (you shouldn’t move on the edge of the board if 
you can avoid it). You can find the code for these functions, along with the rest of the 
source code, on this issue’s CD, Again, most of the work was done by protoBoard. 

REVERSI 

For Reversi, as for Gomoku, we define the name and hoard size but use the default 
piece pictures and board drawing. We also define a setupBoard function which places 
die first four pieces on the board. 

Making a move in Reversi is more complex than in the other games, since existing 
pieces must he reversed. To do this, we override the move function in protoBoard. 
Detenuining whether a move is valid is also more complex, since we require that the 
user flip some pieces. There are no “winning moves” per se. Rather, the game is 
scored when there are no more legal moves. We make this determination in 
makeComputerMove, and then echo it in winningMove and tteGame. Again, see the 
CD for the complete source code, 

THE TAPBOARD APPLICATION TEMPLATE 

While the functionality of making a move by either side is encapsulated in the game 
board templates and the protoBoard proto template, keeping track of whose turn it is 
and which game is being played is the responsibility of the application template. This 
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template also provides Help and Credits buttons and coordinates activities when the 
application opens and doses. 

The Your Move and Computer’s Move radio buttons are simple protoRadioButton 
templates enclosed in the protoRadioCluster. After a user move is recorded, the 
Computer's Move button is turned on. The viewldleScript of protoBoard notices this 
state and makes the computer's move, which in turn sets the Your Move radio button. 

The game selection buttons are also protoRadioButton templates within a 
protoRadioCluster named gamePicker. When the value of these buttons changes, the 
gamePicker elusterChanged function starts the appropriate game by calling the 
newGame function in the application. The newGame function finds the appropriate 
game board and makes it visible; then it starts with the user’s turn, 

gamePicker,elusterChanged ;= func() 
begin 

// Find the name of the new button, 
foreach t in stepchildren do 

if t.buttonValue = clusterValue then 
begin 

// Found it; start a new game with that name. 

:newGame(t.text); 
return ? 

end 

end 

TapBoard,newGame := func(nm) 
begin 

// Look through all the boards, 
local b; 

foreach b in boardList do 

U Are we looking for the one that's currently displayed? 
if nm - nil then 
begin 

// If so, and if this is it, clear it. 
if visible(b) then b:clearBoard(); 
end ; 

i/ If not, check if this is the one that's been specified, 
else if 3trEqual(b.name, nm) then 
begin 

// Set the current board, clear it, show it, and set the 

// piece icons, 

currentBoard : = b? 

b:clearBoard (); 

b;Show()? 
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player1Sample.icon := b.playerlFiece; 
player1Sample:Dirty{); 
player2Samplexicon := b.player2Piece; 
player2Sample;Dirty(); 
end 

// If this isn't it, hide it (harmless if already hidden), 
else b;Hide (); 

// Always start with the user's turn. 

:turn(kUserPiece); 

end 

As a shortcut, newGame uses boardList, an array that lists the available boards (one 
for each of die three games). It could have searched through the entire view list, 
but ids much quicker to have an array that lists just the game boards. This array 
board Li st, is created in the application's viewSetupFormScript and filled in by 
protoBoard’s viewSetupFormScript, 

TapBoard.viewSetupFormScript := func(} 
begin 

boardList := []? 


protoBoard.viewSetupFormScript := func() 
begin 

// Register ourselves with the application. 
AddArraySlot(boardList, self); 


end 

The newGame function also sets an application slot called currentBoard, which keeps 
track of the currently displayed board. 

The two application-level functions below make it easy to set and find out whose turn 
it is. These functions are used within protoBoard and the game boards. 

TapBoard.turn := func(p) 
begin 

userOrComputer:SetClusterValue(p); 
end 

TapBoard.isTurn := func(p) 
begin 

return p * userOrComputer.elusterValue; 

end 
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DISPLAYING INFORMATION 

The announce'Win utility function brings tip protoGlance templates (text views that 
appear for a brief time only) to announce game winning, losing, and tying. Other 
utility functions bring up and remove the “Working...” display. And finally, two utility 
functions bring up the help and credits protoFloatNGo templates (floating views with 
close boxes). AH of these templates are in linked subviews. 

TapBoard.announceWin := func(p) 
begin 

// Make sure the current game display is up to date, 

RefreshViews(); 

// Bring up the right glance view, 
if p - kUserPiece then youWin:Open() 
else if p - kNewtonPiece then iWin:Gpen() 
else tie:0pen(); 
end 

TapBoard,startworking := func() 
begin 

// Open the view, 
working:0pen{); 

// Force a refresh of anything that might need it; we're about to do 
// lots of time-consuming work, so the system won't get a chance to do 
// this otherwise, 

RefreshViews(); 

end 

TapBoard,stopWorking := func() 
begin 

working:Close(); 

end 

TapBoard.announceHelp func() 
begin 

help:Open(); 

end 

TapBoard,announceCredits func() 
begin 

credits:Open(); 
end 

SAVING AND RESTORING THE STATE 

When the application opens, vie wSetupDoneScript checks whether there's a saved 
state in the System soup. If there is, it restores the state. When the application closes, 
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viewQtdtScript saves the state. A utility function, getStateEntry (described earlier), 
returns the current state entry in the System soup, if there is one. 

TapBoard.viewSetupDcneScript := func() 
begin 

// Find the saved state, 

local stateEntry := ;getStateEntry(); 

// Is there one? 
if stateEntry = nil then 

// If not, default to the first radio button. 
gamePicker s setClusterValue(1) 
else 
begin 

//If there is, restore the state from the entry, 
gairtePicker;setByName(stateEntry, name) ; 
eurrentBoard:restorestate(stateEntry); 
end; 
end 

gamePicker.setByKame := func(nm) 
begin 

// Find the radio button with this name and set it. 
local t; 

foreach t in :ChildViewFrames(} do 
if StrEqual(t.text,run} then 
begin 

if clusterValue <> t.buttonValue then 
:setClusterValue(t•fouttonValue); 
return; 

end 

end 

TapBoard,viewQuitSeript func() 
begin 

// If any board is displayed (which it always will be — we're just 
// being paranoid), save the current state, 
if eurrentBoard <> nil then eurrentBoard:saveStatef); 

end 

REMOVING THE SOUP ENTRY 

When the application is removed from the Newton, it needs to remove the entry in 
the System soup so that it doesn't permanently waste Newton memory. This is done 
in the RemoveScript function. Note that this function is called both when the 
application is removed and when the card ids on is taken out of the Neutron. We 
could distinguish these two cases, and not remove the soup entry if ids simply the 
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card being pulled out, but we want to make sure we don’t clutter up precious memory 
with game trivia if die card is never reinserted. 

RemoveScript : = func(packageFrame) 
begin 

local cursor : = Query {Gets tores (> [ 0 ]: Get Soup {RGM_SysteittSoupName), 

{type: 'index, indexPath: “tag, 
startKey: kPackageName, validTest: func(item) 

StrEqual(item.tag r kPackageName)}); 
if cursor:Entry() <> nil then 

EntryRemoveFromSaup(cursor:Entry()); 

end; 

ALLOWING FOR OTHER SCREEN SIZES 

We also need to consider the possibility that TapBoard may be used on a Newton 
with a screen size larger or smaller than that of the first Newton model (240 x 336 
pixels). First w r e define all views in the bottom half of the application window to be 
relative to the bottom of the view, and views in the top half relative to the top. 
Leaving about 20 pixels of space between these two sets of views allows the 
application to shrink by that much, or to grow by a bit We then need to dynamically 
set the bounds of the application to fit the screen, using the system function 
GetAppParams, If the screen is much larger than 240 x 336 we center it instead. .411 
of this is accomplished in the application’s viewSetupFormScript: 

TapBoard.viewSetupFormScript := func() 
begin 

// Remember the original dimensions in case we need them, 
local originalwidth :- viewBounds.right - viewBounds.left; 
local originalHeight viewBounds.bottom - viewBounds.top; 

// Default the app bounds to the screen bounds (nice on small screens). 

local ap := GetAppParams(); 

self *viewBounds := RelBounds(0, ap,appAreaTop, 

ap.appArea Width, ap.appAreaHeight); 

// But if the screen’s too large for that to look good, center it, 

// (We allow for a range of sizes to handle future screens.) 
if ap.appAreaWidth > (originalWidth+20) then 
self.viewBounds«right ;= originalwidth; 
if ap.appAreaHeight > (originalHeight+20) then 
begin 

self.viewBounds.top := ap.appAreaTop + 

(ap.appAreaHeight * originalHeight) div 2; 
self.viewBounds.bottom self.viewBounds.top + originalHeight; 
end; 
end 
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SOME NEWTONSCRIPT EXERCISES 

The following modifications to TapBoard would make good NewtonScript 
programming exercises: 

* Replace the three linked subviews used by announce Win with a 
single template, with different text set programmatically within 
announce Win. 

* Move the Your Alove and Computer's Move radio buttons into die 
protoBoard proto template. Consider the ways this simplifies the 
application and the ways it complicates it. 

* Add an elapsed time display showing how much total time the user 
and the Newton have taken to make their moves. 

* Improve the algorithm for playing Tic-tac-toc, 

* Add Go to the set of games. 

SUMMING UP 

As you've seen, TapBoard reduces code size by using proto templates to abstract out 
the redundant elements of the three games. This also reduces development time by 
making the application simpler, and easier to understand and modify. 

The protoBoard proto template used in TapBoard is fairly large, implementing a 
substantial amount of functionality. Other uses of proto templates are much smaller, 
ranging from custom button types to modified versions of standard views or even 
completely new classes of templates. 

Now you're ready to write some proto templates of your own — assuming you've 
ordered the Newton Toolkit from APDA. Be sure to share your protos with your 
friends! 
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PRINT HINTS 


TRACKING 
QUICKDRAW GX 
MESSAGES 


PETE ("LUKE") ALEXANDER 


In this column, I’d like to bring a tool called 
Message Watcher to your attention. This tool, which is 
provided on this issue’s CD, will help you understand 
the messages sent to your QuickDraw GX printer 
driver or printing extension when an application prims 
a document through the QuickDraw GX system. 

A LITTLE BACKGROUND 

develop Issue 15 gave an overview of QuickDraw GX in 
the article “Getting Started With QuickDraw GX” and 
discussed the QuickDraw GX messaging system in 
“Developing QuickDraw GX Printing Extensions,” 
You can also learn about QuickDraw GX printing and 
messaging in Inside Macintosh: QuickDraw GX Printing 
Extensions and Drivers. If you’ve read these and don’t 
need a refresher, you can just skip to the next section. 

QuickDraw GX’s extensible printing architecture 
makes writing printer drivers easier than ever. Easier 
yet is writing printing extensions, which allow you to 
modify the behavior of the QuickDraw GX printing 
system (similar to the way system extensions let you 
change the system by patching traps). 


default implementation for the associated message, but 
sends a message to the driver anyway. The driver can 
then perform the task in its own way or massage the 
message parameters before forwarding the message on 
to the default implementation. In a printing extension, 
you can intercept and override any message before it 
gets to the printer driven 

ABOUT MESSAGEWATGHER AND OUR EXAMPLE 

With over 150 messages in the QuickDraw GX 
printing system, it’s a little difficult to follow the flow of 
the messages through the system or figure out then- 
default implementation. Message Watcher helps you 
with this by showing the messages being sent while an 
application is printing a document. This “live” view is 
very helpful toward understanding die calling chain 
and hierarchy of messages. 

The Message Watcher application and system extension 
are on this issue’s CD, To use Message Watcher, first 
drop the system extension into the System Folder and 
reboot; then launch the Message Watcher application. 
Whenever any application initiates a print job, a 
window corresponding to that job will be opened in 
Message Watcher and the messages sent as part of the 
job will scroll past. The title of each Message Watcher 
window contains the internal ID of the job. (You 
should view the internal ID of a job similar to the way 
you view a file reference number today.) 

The QuickDraw CX Finder printing extension (which 
is part of the QuickDraw GX system extension) and 
PrinterShare GX are treated like any other applications 
printing through the QuickDraw GX printing system. 
So they each have a print job associated with them, and 
Message Watcher displays windows for them as well. II 
you were co create a desktop printer with the Chooser, 
there would also he a window for the Chooser. 


When an application prints through the QuickDraw 
GX system, QuickDraw GX either performs the 
requested task or sends a message (via the Message 
Manager) to the printer driver to perform the task. The 
QuickDraw GX printing system defines over 150 
messages. For many tasks, QuickDraw GX provides a 


As an example, we’re going to print a document created 
and displayed by die “All Shapes with Printing” sample 
application, which is part of the sample code included 
widi QuickDraw GX. This sample creates all of the 
shapes possible within the graphics system. Below is the 
code that prints the page ol shapes; keep it in mind 


PETE ("LUKE") ALEXANDER will lelL you that life al Apple is 
hard. He spends long days (and frequent nights) with smart people 
trying to figure out what the right thing is and how to make if 
happen. Then he gets sent all over the world to tell people about 
what's new and happening. Last year Luke went to London and 
walked around the streets for ten hours trying to fend off jet lag 
and punk rockers, to Madrid where he had an unforgettable 
chocolate shake, to Milan where he saw the basement of the Apple 
building and tried not to take it personally that they wouldn't let 


him near a window, to Munich and Frankfurt where he finally 
understood why Germans gush about their beer, and to Sweden 
where he gave his QuickDraw GX talk in a discotheque filled with 
engineers who couldn't get the beat. After these whirlwind tours, 
Luke soars above the stress in his glider, but only occasionally 
takes an Apple Evangelist along, since they seem to think they've 
got connections up there and are forever telling him how to fly. Yes, 
life at Apple Is hard, but after five years, Luke's beginning to get 
the hang of it* 
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while going through the example of using 
Message Watcher in the next section. 

OSErr DoPrintOneCopy (WindowPtr mywindow) 

{ 

Str255 windowTitle; 

OSErr printError = noErr; 

if (myWindow) 

{ 

GetWTitle{myWindow, windowTitle); 

// Start sending the job. The job has the 
// same name as our window and contains 
// one page. This name appears in the 
// status messages sent to the desktop 
// printer. 

GXStartJob(gDocumentJob, windowTitle, 1); 

// Send the entire page of shapes to'the 
// printer. (All the shapes being printed 
// have been collected into the GX picture 
// shape: gthePage.) 

GXPrintPage(gDocumentJob # 1, 

GXGetJobFormat(gDocumentJob, 1), 
gthePage ); 

// Tell QuickDraw GX printing we‘re done 
// sending the job, so terminate the 
// spooling process. 

GXFinishJobfgDocumentJob); 

if (GXGetJobError{gDocumentJob) 1- noErr) 
// Your error-handling code here I 

} 

} 

We’re going to look at our sample application printing 
to a LaserWriter II SC, so the message sequence 
displayed by Mess age Watcher contains messages that 
are sent to a raster printer. Note that most of the 
messages would he different tfwe were printing to a 
PostScript® printer or to a plotter. 

Each line in a Message Watcher window consists of a 
message preceded by one of die following labels: send 


THE RETURN OF ! STR * (-8192) 

In the Print Hinfs column in Issue 13 of develop , I 
talked about the disappearance of 'SIR ' (-81 92) 
and TARA 1 [-8192) resources from a system running 
QuickDraw GX and how your application should be 
prepared to handle this situation. The 'PAPA 1 (-8192) 
resource is still gone, but the r STR 1 (-8192) resource, 
containing the name of the default printer driver, has 
returned. Unfortunately, there are a few applications 
that require this resource to be present to run 
correctly — in some cases, to run at oil. Since we 
wanted old applications to have the highest possible 
compatibility while printing through a QuickDraw GX 
system, we put the resource back. However, as 
mentioned in Issue 13, it's still not a good idea to 
depend on the information in ’SIR r (-8192). 


message, send object, and send object to. These labels 
represent the similarly named API calls in the Message 
Manager— for example, “send message" corresponds 
to the SendMessage call. All the “send" labels are 
roughly equivalent, so you’ll he able to follow along 
well enough without distinguishing between them; if 
you do want more information about the Message 
Manager calls, see Chapter 6, “Message Manager," in 
Inside Macintosh: QuickDraw GX Environment and 
Utilities . 

While going through the various Message Watcher 
windows in the next section, I won’t bore you with a 
line-by-line discussion of everything displayed in each 
window. I’ll give you the general idea behind the 
information presented; by checking out the 
documentation and trying out Message Watcher 
yourself on different applications, you’ll be able to 
figure out these details easily enough. 

WHAT MESS AGE WATCHER DISPLAYS 

The first time our sample application calls the 
QuickDraw GX printing API, the QuickDraw GX 
Finder printing extension initializes the default printer 


PRINT HINTS: TRACKING QUICKDRAW GX MESSAGES March 1994 







and then shuts down. The Message Watcher window 
for this extension contains the following {the window 
title is shown in boldface; the ID displayed in each title 
will be different when you run Afesage Watcher 
yourself): 

Finder: QxOOQQfac4 

send object to: initialize 
send object; defaultPrinter 
send object to: shutDown 

You 1 !! also see PrinterShare GX start up a couple of 
dines: The first time, it performs some general spool 
file and desktop printer queue management; it 
examines all the spool files and makes sure that the 
print jobs that are waiting are handled in the 
appropriate order- The second time it runs, it starts 
up the print job. The MessageWatcher window for 
PrinterShare GX displays this: 


PrinterShare GX: 0x0000fa3c 

send object to: initialize 
send object: defaultPrinter 
send object to: initialize 
send object; defaultPrinter 
send object: defaultPaperType 
send object; defaultFormat 
send object: defaultJob 

send object: defaultPaperType 
send object to: shutDown 


Notice that MessageWatcher indents some of 
information in the window, allowing you to see the 
message hierarchy. For example, the above window 
shows that the recipient of the defaultjob message 
sent the message in the indented line below it, 
d efau 1 tPap erTyp e. 


The next application to send messages through the 
system is our sample application, All Shapes with 
Printing. In this case, xve chose Print One Copy from 
the File menu of the application to start the printing 
process. The application starts by setting up various 
default printing structures associated with the print job. 


All Shapes with Printing: 0x00990c 

send object to: initialize 
send object: defaultPrinter 
send object to: initialize 
send object: defaultPrinter 
send object: defaultPaperType 
send object: defaultFarntat 
send object: defaultJob 

send object: defaultPaperType 


Now r we 1 !! sec the actual messages sent to print a 
document. Our sample application is ready to start 
up the print job and create the spool file. It uses 
GXPrintPage to print the document; you’ll see the 
startjob and finishjob messages in the MessageWatcher 
window because GXPrintPage sends these messages in 
its default implementation. Next, the data contained on 
the page is spooled to disk. Finally, the print job is 
finished, and the spool file is closed and waiting for 
PrinterShare GX to find it and send it to the printer. 


send message: createSpoolFile 
send object: jobStatus 
send object: printPage 
send message: StartPage 
send object: jobStatus 
send message: finishPage 
send message: spoolPage 
send message: spoolData 
send message: spoolData 
send message: spoolData 
send message; spoolData 
send message: spoolData 
send object: finishJob 

send message: completeSpoolFile 
send object: spoolResource 
send object: jobStatus 
send object to: shutDown 


The QuickDraw GX printing system is now ready to 
send the data contained in the spool file to the printer. 
PrinterShare GX starts by checking the status of the 
printer and then writing (that is, sending) the data. It 
continues to w rite the data and check the device status 
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until all the data is sent. If a status check were to reveal 
that an error had occurred, the error would be available 
via GXGetJob Error to the driver or extension (not to 
the application, which is usually out of the printing 
process at this point). Once all the data has been sent to 
the printer, PrinterSha re GX checks the status of the 
printer one last time, makes sure the print job was 
successful, closes the spool Ole, and shuts down. We 
now have a piece of paper coming out of the printer. 

PrinterShare GX; 0x00092520 

send message: getDeviceStatus 
send message: writeData 

send message: getDeviceStatus 

lots of writeData and getDeviceStatus 
messages to send the data to the printer 
send message: writeData 
send message: checkStatus 
send object: jobStatus 
send object: cioseSpoolFile 
send object to: shutDown 

The Message Watcher window for the QuickDraw GX 
Finder printing extension shows the messages it 
receives to update the status information being 
displayed in the desktop printer’s window. In this case, 
the status is updated six times during the process of 
printing the document. To see exactly what status 
information is being sent to the desktop printer’s 
window, you could open the w indow yourself and take 
a look. Remember, the messages will be slightly 
different for different types of printers — PostScript, 
raster (QuickDraw based), and plotter. 


Finder: 0x00D912dc 


send object: 
send object: 
send object: 
send object: 
send object: 
send object: 


writeStatusToDTPHindow 
writestatusToDTPWindow 
writeStatusToDTFWindow 
writeStatusToDTPWinriow 
writeStatusToDTPWindow 
writestatusToDTPWindow 


WATCH OUT NOW . . . 

Following the flow of messages through the 
QuickDraw GX printing system will give you a better 
understanding of the calling chain and hierarchy of 
messages that are sent while a document is being 
printed. With Message Watcher, you have the power to 
peek into the world of QuickDraw GX messaging. 
Happy exploring! 


REFERENCES 

* Inside Macintosh: QuickDraw GX Printer Drivers 
and Extensions and inside Macintosh: QuickDraw 
GX Environment and Utilities. On-line versions 
accompany QuickDraw GX releases; printed 
manuals will soon be available (Addison-Wesfey 
1994). 

* "Getting Started With QuickDraw GX" by Pete 
("Luke") Alexander and "'Developing QuickDraw 
GX Printing Extensions" by Sam Weiss, develop 
Issue 15. 

* "Print Hints: Looking Ahead to QuickDraw GX" by 
Pete ("Luke"] Alexander, develop Issue 1 3. 


Buried deep within QuickDraw GX is on About box. The 
exercise of how to get to this box is left for the reader/ 


Thanks to Hugo Ayala, Tom Dowdy, and Dave Mersey for 
reviewing this column/ 
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STANDALONE 


CODE ON 
POWERPC 


A new format for standalone code in the PowerPC world brings 
increased functionality and easier implementation. You'll no doubt want 
to port existing code resources and write plug-ins for the new platform. 
Here you'll learn how to do both while also retaining or building in the 
ability to run the standalone code on the old 680 x 0 platform. 


TIM NICHOLS 


Standalone code is an important part of the Macintosh environment and will 
continue to be in the age of the PowerPC processor. Such code takes many different 
forms and serves many different purposes. It can serve as a definition function — 
such as an MDEF or a WDEF — for Macintosh system software, act as a dynamic 
extension to an application, or find other, more esoteric uses. In the PowerPC world, 
it can also he used to port time-critical portions of an application written in 680x0 
code. 

This article shows you how to develop and package standalone code modules to run 
in both the PowerPC and 680x0 worlds. We start by discussing the differences 
between standalone code in the two runtime environments. Then we go through the 
steps of compiling, linking, and packaging different types of standalone code, and 
calling it from within your application. We look at the Following: 

* how an application can support a plug-in that contains code in 
both the 680x0 and PowerPC formats, illustrated by preparing a 
plug-in sort algorithm for a simple application called SuperSort 

* how to use a similar mechanism to port time-critical portions of an 
existing application to the PowerPC platform 

* how to make an existing WDEF into a “fat” resource — one that 
w ill work in cither a 680x0 or a PowerPC environment, depending 
on the machine executing the code 

SuperSort, the plug-in, and the WDEF, along with their source code, arc all on this 
issue’s CD. All the code can run {in either the 680x0 or the PowerPC] platform, 
although you do need MPW to compile it. 
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This article assumes that you know how to write a standalone code resource for the 
680x0 platform and that you have a general grasp of PowerPC technology and 
runtime architecture, 

THE STORY ON STANDALONE CODE 

The format of standalone code has changed in the PowerPC world. Standalone code 
in the 680x0 world is packaged in resources such as WDEFs and IN1 Ts t with limited 
functionality and significant restrictions on their implementation. PowerPC 
standalone code, on the other hand, can be packaged as a resource or stored in die 
data fork of a file and enjoys a more flexible and powerful mechanism for managing 
global data and importing and exporting functions based on shared libraries. 

STANDALONE CODE IN THE 680X0 WORLD 

In die 680x0 world, developers can write two types of code; applications and 
standalone code. Applications have special privileges that aren't available to 
standalone code. Perhaps the most notable is the ability to easily access global and 
static data via the A 5 world. The A5 register is maintained by the Process Manager 
for each application, to facilitate access to the QuickDraw global data as well as 
application global and static data. All references to global and static data by the 
application are made via the A5 register. 

By contrast, standalone code resources have no AS world and therefore don't have 
access to global or static data. This can limit the functionality of the code. There are 
mechanisms to get around this limitation, but they differ from one environment to 
the next. THINK C has a mechanism for using A4 as a pointer to global data for 
standalone code, while MPW uses special functions and macros to create a pseudo AS 
world for the code resource. Both of these place a burden on developers by forcing 
them to set up and restore the appropriate registers before they can access their 
globals, 

STANDALONE CODE IN THE POWERPC WORLD 

In the PowerPC world, there’s only one type of code, known as a code fragment. A 
code fragment is a collection of code and its corresponding data. Fragments can be 
packaged in a number of different kinds of containers, A PowerPC application 
consists of one or more code fragments packaged in the data fork of die application. 
Part of die Macintosh system software consists of code fragments packaged in the 
Macintosh ROM. Standalone code is really just another code fragment packaged in a 
resource or in die data fork of a file. 

Whether standalone code is packaged in a resource or in die data fork depends on 
how ids being used. If you’re writing a PowerPC version of an existing code resource 
such as a WDEF or an XCMD, the standalone code should be packaged in a 
resource, for purposes of compatibility. (The existing code only know s to look for 


For more on standalone code in the 680x0 
world, see the Macintosh Technical Note "Stand- 
Alone Code, ad nauseam" and the article 
"Another Take on Globals in Standalone Code" 
in develop Issue 12 * 


For an overview of PowerPC technology 
and runtime architecture, see the article "Making 
the Leap to PowerPC" in develop Issue 16 and 
the saonTobe-a variable Inside Macintosh: 
PowerPC System Software * 
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code in resources of a specific type; for example, the Window Manager only looks for 
window definition functions in resources of type 'WDEF',} If, on the other hand, 
you 1 re developing a new standalone code module as a plug-in or to accelerate some 
part of your application, the standalone code should be stored in the data fork of your 
application or plug-in file to fully exploit the PowerPC runtime environment. Code 
can be loaded rapidly and efficiendy from the data fork of a file without using a large 
memory footprint, thanks to the mechanism of file-mapped virtual memory. 

Fragments can export symbols (code or data) by name to other fragments and can 
import symbols by name from other fragments. Each fragment contains an array of 
pointers known as the table of contents (TOC), which allows die fragment to share 
symbols with odier fragments and is used to reference the fragment's own global and 
static data. Each entry in the TOC is a reference to either an imported symbol from 
another fragment or a static data item in the fragment itself. For example, suppose 
the code fragment Foo exports a procedure DoThis, contains a single global variable 
gMyGlobal, and imports a function DoThat from the shared library Bar, The TOC 
will contain an entry for each one of these symbols (DoThis, DoThat, gMyGlobal), 
and each entry will point to the address of the corresponding symbol, as shown in 
Figure 1. 



Foo's TOC Code Fragment Foo Shared library Bar 


Figure 1 

A Fragment's Table of Contents 


The R2 register in the PowerPC processor is dedicated to storing the currendy active 
TOC and thus is sometimes called the RTOC. The RTOC is saved, modified, and 
restored each time a new fragment is invoked. Because the TOC allows references to 
global and static data, ids analogous to the A5 world in the 680x0 environment. 
However, it’s important to emphasize that in the 680x0 environment only 
applications have an AS w r orld and easy access to global and static data, wdiile in the 
PowerPC environment, all fragments have a TOC and easy access to global and static 
data. So the great thing about standalone code being handled as a code fragment is 
that you can have globals in your WDEFs, INITs, and plug-ins without having to 
jump through any hoops at all! 















Because a fragment can contain symbols from other fragments, these symbols must 
be resolved or bound at run time. This preparation is performed by the Code 
Fragment Manager. In most cases, such as when a PowerPC application is loaded, 
this is done transparently. Standalone code can be automatically prepared by the 
Mixed Mode Manager, but the preferred method is to have your application call the 
Code Fragment Manager directly Fortunately, the Code Fragment Manager makes 
this an easy task, as we’ll see later. Once a fragment has been prepared, the Code 
Fragment Manager returns a connection ID to identify the fragment. This 
connection ID is used when unloading the fragment, similar to a refNum that’s 
returned when opening a file and later used to close the file. 

The Code Fragment Manager has the ability to resolve symbols by name, so you can 
export any routine or data by name and then import that symbol in another fragment. 
This allows you to store multiple routines in your fragment, export them, and then 
eall each routine when necessaiy by asking the Code Fragment Manager for its 
address. This is much nicer than having a dispatch-based, single-entry-point code 
resource as we do in die 680x0 environment. 

CALLING STANDALONE CODE 

At any given time a PowerPC processor-based Macintosh may be executing in the 
native PowerPC runtime architecture or in an emulated 680x0 runtime architecture. 
The switching between the two runtime environments is transparent and handled by 
the Mixed Mode Manager. And thanks to the Mixed Mode Manager, code from one 
instruction set can call code from another instruction set, which is just w hat happens 
when a 680x0 application calls a standalone code module written in PowerPC code or 
a native PowerPC application calls a standalone code module written in 680x0 code. 

So whenever we’re running on a PowerPC processor-based Macintosh and our 
application calls standalone code, we’re presented with an interesting problem. Given 
a pointer to standalone code, how do we know what kind of code it points to? In the 
680x0 world, a procedure pointer is simply the address of a procedure. But in the 
PowerPC environment, a procedure pointer is actually the address of a transition 
vector, which in turn contains pointers to the actual routine and the TOC for the 
fragment. Figure 2 shows the difference. 

To solve this problem, the Mixed Mode Manager creates a generic procedure pointer 
known as a UniversalProcPtr (UPP). A UPP can point to one of two things: a 680x0 
procedure (in which case the UPP is really just a 680x0 ProcPtr in disguise) or a 
routine descriptor (data type RoutineDescriptor). A routine descriptor is a data 
structure that describes the instruction set, parameters, and calling convention of the 
routine. The Mixed Mode Manager looks at the routine descriptor to determine 
whether a mode switch is necessary and, if so, how to perform the switch. 

To run in a PowerPC environment, we use a UPP anywhere we would formerly have 
passed a ProcPtr, such as in specifying a dialog filter procedure. In the ease of 680x0 
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standalone code (which typically is stored in a resource), we indirecdy pass a ProcPtr, 
and thus a UPP, to the calling routine via the handle to the resource. For a PowerPC 
code resource (or for a “fat” resource), we have to replace this ProcPtr with a UPP, 
which points to a routine descriptor describing the routine in our code resource. 
Figure 3 compares the forms taken by the three different kinds of code resources 
(680x0, PowerPC, and fat). 

Now that you have the necessary background information on standalone code, we can 
move on to demonstrate how to handle three different types of standa l one code: a 
universal plug-in module, a module to port time-critical code, and a fat resource. 



Figure 2 

680x0 and PowerPC Procedure Pointers Com pored 



Fat 


Figure 3 

Forms of Code Resources Compared 
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A UNIVERSAL PLUG-IN MODULE 

Plug-ins are a popular way for third-party developers to extend the functionality of an 
application. To demonstrate how to create and support a universal plug-in module — 
one that will run in either the PowerPC or the 680x0 world — well use the example 
of a plug-in module for an application called SuperSort, which you’ll find on this 
issue’s CD. 

SuperSort is a simple application that visually sorts data represented as bars of 
varying height according to a specified algorithm. SuperSort has two built-in 
algorithms — bubble sort and quick sort — and can add new algorithms through a 
ptug-in mechanism. We’ll compile and package a she 11-sort algorithm into a plug-in 
that will work with either the 680x0 or the PowerPC version of SuperSort. The 
application will pick the correct version of the plug-in automatically at run time. 

EXAMPLE CODE 

Below is the code for our plug-in sort routine that implements the shell-sort 
algorithm. ShellSort’s data parameter is a pointer to the data to be sorted, the size is 
the number of elements to be sorted, and the swap parameter is a callback procedure 
to SuperSort to animate the sort. 

linclude "SortPlugXn.h" 

#if powerc 

#include <MixedMode.h> 

ProcInfoType swapPI = kCStackBased 

I STACK_ROOtriNE_PARAMETER{l, kFourByteCode) 

I STACK_R00TINE_PARAMETER(2, kFourByteCode}; 

Iendif 

void ShellSortfDataFoint Mata, short size, SwapProc swap); 

void ShellSort(DataPoint Mata, short size, SwapProc swap) 

{ 

short i, j, incr; 

incr = size / 2; 
while finer >0) { 

for (i=incr; i<size; i++) { 
j - i - incr; 
while (j >= 0) { 

if (data[j].n > data[j + incr].n) { 

#if powerc 

//We must use CallUniversalProc since we will be passed a 
// LfPP for the SwapProc, 

CallUniversalProc(swap, swapPI, &data[j], &data[j + incr]); 


For details on the shell-sort algorithm, 

see any book on algorithms, such as 
Fundamentals of Computer Algorithms by 
Horowitz and Sahni or Data Structures and 
Algorithms by Aho, HopcroFt, and Ullmam* 
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ielse 

// If we r re 680x0, we can just call the proc directly* 

// MixedMode will handle switching if swap is a UPF* 

(*swap)(&data[jj, &data[j + incrj)? 

#endif 

j -= iner; 

} else 

j = -1? 

} 

} 

incr /= 2; 

} 

} 

COMPILING, UNKING, AND PACKAGING 

We execute the following commands to compile and link this procedure in order to 
create the 680x0 version stored in a T SORT r resource: 

C ShellSort.o -o ShellSort.o 

link -t 'rsrc' -c 'RSED' -m ShellSort -rt SQRT=128 ShellSort.o d 
-o ShellSort.rsrc 

We compile and link the procedure again to create the PowerPC version to he stored 
in the data fork The output of the PowerPC linker is known as an XCOFF (extended 
common object file format) file. This is a bloated file that we then strip to turn into a 
leaner file known as a PEF file (your guess as to what PEF stands for is as good as 
any)* Here are the commands: 

PPCC -w conformance -appleext on -sym full ShellSort.o -o ShellSort.c.o 


PPCLink -main ShellSort -export ShellSort r) 

ShellSort.c.o d 

n { PFCLibr aries >" StdCRuntime. o r) 

" {PPCLibraries > "PPCCRuntime. o r) 

-o ShellSort.xcoff 

makepef ShellSort,xcoff -e ShellSort 3 

-o ShellSort.pef 


Now that we have the two pieces, we join them together: 

duplicate -y -d ShellSort.pef ShellSort 
duplicate -y -r ShellSort.rsrc ShellSort 
SetFile ShellSort -t 1 SORT p -c 'TimN' 

The resulting file, ShellSort, is our plug-in that can be executed on either the 680x0 
or the PowerPC platform. The code fragment that’s stored in the data fork will be 
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loaded, prepared, executed, and unloaded by the PowerPC version of the SuperSort 
application, while the code contained in the 'SORT' resource will be loaded, 
executed, and unloaded by the 680x0 version. 


CALLING THE PLUG-IN 

When calling a universal plug-in, your native PowerPC application should first check 
to see whether there’s a code fragment in the data fork of the plug-in, using the Code 
Fragment Manager routine GetDiskFragment* If so, the pointer returned by 
GetDiskFmgment can he used to call the module. If not, the application should then 
look for die appropriate plug-in resource in die resource fork of the plug-in. 

GetDiskFragment locates and loads a fragment found in the data fork of a file. 

OSErr GetDiskFragment(FSSpecPtr fileSpec, long offset, long length, 

Str63 fragName, Mask findFlags, ConnectionID *connID, 

Ptr *mainAddr, Str255 errName); 


The parameters are as follows: 


fileSpec 

offset 

length 

fragName 

findFlags 

connlD 

mainAddr 

errName 


The file to check for a fragment 

Offset into the data fork where the fragment resides 

The length of the fragment, in bytes 

The name of the fragment, used for debugging only 

The operation to be performed on the fragment 

The fragment connection ID 

The main entry point of the fragment 

The error string returned if the call fails 


Here’s an example of how you might call a universal plug-in: 


Handle 
MyProcType 
OSErr 

ConnectionID 


myProcHandle; 
myProcPtr; 
err; 
connlD; 


err = GetDiskFragment(theFile, 0, 0, theFile.name, kLoadNewCopy, 
GconnlD, &myProcPtr, errName); 
if (err == noErr) { 

/* We have a fragment, ladies and gentlemen! */ 

{*myProcPtr)(pi, p2, p3); 

CloseConnection(connlD); 

} else 

{ 

/* We have a resource. */ 

myProcHandle = GetlResource(kMyCodeType, kMyCodelD); 
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if (myProctiandle 1= nil) { 

HLock(myProcHandle); 

myProcPtr = (MyProcType)*myProcHandle; 

#if powerc 

CallUniversalFroc(myProcPtr, kMyProdnfo, pi, p2, p3); 

#else 

(*myProcPtr)(pi, p2, p3); 
fendif 

HUnlock(myProcHandle); 

ReleaseResource(myProcHandle ); 

} 

} 

The address that’s returned is whatever symbol was defined as the main entry point 
during the linking of the PowerPC code. Because this is a true pointer to the routine 
and not a routine descriptor, it can be dereferenced and called direedy as with any 
other ProcPtr you may be used to. 

If your fragment has multiple entry points, you can use the Code Fragment Manager 
function Find Symbol after loading the fragment via GetDiskFragment in order to 
locate a particular symbol by name. The FindSymbol routine returns the address of 
die symbol you request. 

A MODULE TO PORT TIME-CRITICAL CODE 

To port only time-critical portions of your application, you would use a technique 
similar to the one just described. Factor out the code whose execution you want to 
accelerate, create a fragment, and package the fragment in the data fork of your 
application* In your application’s initialization code, call the Code Fragment Manager 
to get the entry point to diis fragment from your application’s data fork and store this 
poin ter. When you no longer need the pointer, call the Code Fragment Manager to 
close the connection to the code fragment. 

Your code fragment will need a routine descriptor as its main entry point since it will 
he called from 680x0 code. To make a routine descriptor your main entry point, 
declare a global routine descriptor in your code that describes the fragment’s main 
entry point. When you link the resulting object file, tell the linker to use this global 
routine descriptor rather than the actual code entry point as the main entry point* 

Here’s an example of using a global routine descriptor as an entry point to a 
fragment: 

RoutineDescriptor MyEntryPointRD = 

BUIL D_R0U TINE_DESCRIPTOR(kMyEntryPointProcIn fo f My Entry Point) 
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When we go to link this code, we tell the linker that the main entry point is our 
routine descriptor. 

link “main MyEntryPointRD -export MyEntryPointRD {MyQbject} {MyLibs} 8 
-o {MyXCOFF} 

A FAT RESOURCE 

Although existing resources can run on a PowerPC processor-based Macintosh 
thanks to the 680x0 emulator, they run much more slowly than they would if they 
were written in native PowerPC code. If you make an existing resource “fat,” it will 
work in either the 680x0 or the PowerPC environment and you w on't need to ship 
two different versions of your resource. For example, if you have a fat WDEF, the 
code will run as usual on the 680x0 platform but w ill execute as native PowerPC code 
on the PowerPC platform, with the Macintosh system software choosing the correct 
code at run time. 


CREATING A FAT RESOURCE 

There’s a template defined in MixedMode.r that allows easy creation of fat resources. 
Well create a fat resource version of a WDEF to show how it's done. We won’t 
present all of the code here but simply the steps involved in making the WDEF into a 
fat resource. The code for the WDEF is on this issue's CD along with an application 
called TestWDEF that shows the WDEF working. 

Recall from our earlier discussion that we call a code resource through a ProePtr, 
which in this case is a dereferenced resource handle. That means that we need to 
create a routine descriptor for our PowerPC version of the WDEF so that the Mixed 
Mode Manager can invoke a mode switch, if necessary, when the system software 
calls the WDEF* This is consistent w ith the requirement that all ProePtrs be replaced 
with UPPs in native PowerPC code. 


Here’s an example of a fat resource Rez definition: 
^include "MixedMode.r" 


type 'WDEF 1 as ‘sdes'; 


resource 1 WDEF* (128) { 


OxOOO()3BBO , 



// 

0x00QO3BB0, 



/! 

$$Resource("WDEF.rsrc" , 

'oCod', 

123), 

n 




n 

SSResource("WDEF.rsrc", 

■pCod 1 , 

123) 

a 




u 


}; 


680x0 Proclnfo 
PowerPC Proclnfo 
Name, type, ID of resource 
containing 680x0 code 
Name, type, ID of resource 
containing PowerPC code 


MixedMode.r is part of the Macintosh on 
RISC Software Developer's Kit, soon to be 
available from APDA. * 
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The resource type 'sdes' is defined in MixedMode.r. The 'sdes* resource template 
inserts into the start of your resource some 680x0 code that checks whether you T re 
running on a PowerPC platform* If so, it copies your PowerPC code to the start of 
the resource data in memory and calls the PowerPC code via a UniversalProcPtr 
embedded in the resource at the start of the PowerPC code* Once the PowerPC code 
has been copied, each subsequent call to the resource goes straight to the PowerPC 
code, bypassing the initial checks* If you're running on a 680x0 platform, the same 
process occurs, but instead the 680x0 code is copied over the resource data in 
memory. All of this is done transparently by the 'sdes' resource template* 

CALLING THE FAT RESOURCE 

If your fat resource was created using the template in MixedMode.r, you don't have to 
change your calling code to execute the PowerPC code fragment. Calling PowerPC 
standalone code is exactly the same as calling 680x0 code. Due to the magic of the fat 
resource, the calling code doesn’t have to know the PowerPC processor even exists. It 
simply grabs the resource and calls it* 

Here's what the code looks like: 

Handle myProcHandle; 

MyProcType myProcPtr; 

myProcHandle - Get 1 Resource(kMyType, kMylD); 
if (myProcHandle “ nil) { 

// Handle the error, 

} else 

{ 

HLock(myProcHandle)? 

myProcPtr = (MyProcType}*myProcHandle; 

(*myProcPtr)(/* Params go here* */}; 

HUnlock{myProcHandle); 

ReleaseResource[myProcHandle); 

> 

When tliis code is compiled into 680x0 code, the parameters are placed on die stack 
and the actual routine is called via a 680x0 JSR(AO) instruction. When the JSR 
instruction is executed, the pointer in A0 points to a routine descriptor, not to 680x0 
code. This causes the emulator to invoke the Mixed Mode Manager, which then 
performs the necessary context switch, automatically prepares the fragment for 
execution, and calls the PowerPC code* Upon exit from the PowerPC code, the 
Mixed Mode Manager performs a switch back to the emulated 680x0 environment 
and execution continues as if the call were to 680x0 code. The calling code never 
knows the difference* 
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NOW WHAT? 

Now that you’ve learned the basics of standalone code on the PowerPC platform, you 
can start thinking about what you can do with your application or existing code 
resource to exploit the speed of the PowerPC processor, A good exercise is to consult 
your favorite algorithm book and create your own SuperSort plug-in using a different 
algorithm, or to recompile your favorite WDEF or other code resource into a fat 
resource that you can run on any Macintosh, whether PowerPC processor-based or 
680xG-based. Remember to package your new code fragments in the data fork, and 
your recompilations of existing resources as resources. Then watch your creations 
take off! 
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DAVE JOHNSON 


it s the only profession where you don't need to wear shoes 
to meetings? b it because you get to hang out with smart 
people? 

Unfortunately, while this accurately conveyed my 
enthusiasm for die subject, it also completely shredded 
any objectivity my survey might have had, and skewed 
the results sharply toward the tight, square little box of 
my preconceptions* Note that the top reason appears in 
this list, and furthermore it appears first. Coincidence? 

I think not* As one alert respondent pointed out, I even 
blurred the important distinction betw een what makes 
programming interesting and what makes it a nice 
business to be in. Sheesh. 


In the interest of pushing back the boundaries of 
human knowledge in my own small way, I decided to 
conduct a litde survey via e-maih I asked only one 
question: 

What's so interesting about programming computers, 
anyway? 

I sent out 87 letters and received 37 direct responses, a 
43% return rate! This is a fantastic return rate for a 
survey. As one respondent wrote: What an interesting 
survey! Getting hackers to talk about themselves should be 
easy! 

It was, 

lb alleviate your suspense, here are the top two reasons 
programmers program, according to mv survey: 

1. Programmers like solving problems and puzzles. 
(49%) 

2, Programming is a creative oudet. (36%) 

In the survey itself I included some hypothetical 
answers to my own question, as follows: 

Do you just like doing puzz les? Is it the money ? Was it a 
horrible accident, and you were supposed to be a doctor 
ivhen you grew up? Is it because you 're really an artist, 
and computers are the best medium around? Is it because 


Abandoning rigor and embracing whimsy, I decided to 
clump all the responses into one big text file and do a 
w r ord frequency analysis of the whole thing, logging 
how many times each word appeared* Ignoring the 
common words like the and the expected words Like 
program , the winner was problem , at 12 occurrences. 
Game came in a close second, at 11 appearances* Three 
words tied for third place, at 8 occurrences :fun, 
interesting) and dunk. Now tins is a satisfying analysis! 

Other frequently appearing words w r ere these: puzzle , 
art , control, creation, enjoy , paid , challenge, complex , 
efficient, god , high, hooked, money, music, play , and solving. 
Taken together, they make a strangely accurate mantra 
about what programming is like, and prohably describe 
in a more complete way than any individual answer 
why people program. 

But let's look again at those top two reasons. In second 
place w r e have “Programming is a creative outlet” That 
fact w r as mentioned over and over again, but creativity 
comes in many varieties, and it’s interesting to look at 
the metaphors people chose to describe the act of 
wanting software. Interestingly, they fell into three 
very distinct categories: programmer as mechanic, 
programmer as artist, and programmer as God* 

The similarities between computer programming and 
mechanical engineering may be deeper than it seems at 
first glance: 


DAVE JOHNSONS favorite book between the ages of 5 and 1 1 
was the World Book Encyclopedia . Sometimes in the early 
mornings, before anyone else was awake, he'd sneak out of bed, 
creep quietly through the dark and silent house to the living room, 
and slip a volume from the shelf. ("M" is fondly remembered to this 
day: matches, monsters, motors * * . ] Stopping off in the kitchen for 
a stack of cookies, he'd make his way back to his bed, and stoy 
there reading and generating crumbs as the sun came up.* 
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/ got hooked on erector sets when 1 was young. 

—John Powers 

But if programmers are just frustrated machinists, then 
why don't they get up from their computers and build 
real machines? Here’s why: 

On a computer ,; I can b uild an amazingly fantastic and 
elegant gadget with thousands of working parts all 
cooperating pleasantly with one another ; and I never have 
to get my hands dirty. 

—Jeremy Nguyen 

If you’re willing to build your machines behind the 
glass of a computer monitor, to build them out of 
logical stuff instead of real stuff, then suddenly the 
landscape of possible machines becomes effectively 
infinite* You can build any machine you can think of, 
and all those pesky, annoying details like friction anti 
inertia and tensile strength just fall away. For people 
who like to design machines, and especially for those 
who aren’t so keen on the grease and skinned knuckles, 
this is a powerful attraction. 

Other people chose to compare programming with 
creating art: 

Tm not very good at an , but when I write something 
that works well I feel like an artist creating a piece of 
arTwork. 

— Kevin Mellander 

My father is a painter, and I grew up watching him 
continually producing new artwork * *. Software isjust 
another medium , less messy, easier to change . 

— Fred Huxham 

Programming is definitely a means of expression, and 
unlike other media software can simulate every other 
medium; in Alan Kay’s w r ords it’s a meta-medium. For 
those with an artistic leaning this is rich ground, 
indeed: you can create your art and you can create new r 
ways of creating art. 


My own favorite creation metaphor is programmer as 
God: 

/ like it because you can play God , albeit on a microscopic 
scale. It's hard to explain , but writing code is like creating 
new life . 

— Dave Hersev 

// is the closest I can get to being God (without lifetimes 
of sadhana). I get to sculpt a little L Hfe-form ” that, while 
admittedly unsophisticated, has a satisfying degree of 
autonomy. 

— Corey Vi an 

Since software is something that’s dynamic in time and 
semi -autonomous, it can fairly convincingly imitate 
living things, in much the same way that machinery 
often can. But since the software “machines* that 
computers allow us to construct can he orders of 
magnitude more complex than machines in the real 
world, their resemblance to life can be much more 
compelling, much more striking. 

The joy of solving problems (or the compulsion to sol ve 
them, as the case may be) seems to be the ma jor reason 
people program. My favorite survey response of all 
sums this up nicely: 

The reason I program is because I 'm a compulsive 
problem solver and my computer is a never-ending source 
ofproblems. 

— Craig Prouse 

It’s the twin meaning of “never-ending* that I love so 
much here. The fact that the problems never end is one 
of those “both blessing and curse* features that 
computers seem to overflow with* On the one hand, it 
means that we have an inexhaustible source of puzzles 
and problems to slake our thirsts, but on the other 
hand it means that we can never really be finished, and 
like Sisyphus rolling his stone up the hill, we are 
doomed to repetitive toil, solving the same kinds of 
puzzles over and over again* 
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Here are some of the other reasons people gave, which 
didn’t fall neatly into any category: 

Its basically because I have alt these ideas in my head , 
and a computer is the best way to get them OUT of my 
head . .. 

—Jeff Barbose 

Solving the problems is fiat, but I must admit that I 
enjoy the company of the machine — it V not every day 
you meet somebody who will associate with you 
unconditionally. 

— Steve Beitzel 

/ program to get hack at my senior year English teacher 
I once got a bad grade on an English paper .; and she 
couldn V give me any concrete reasons why , She just didn V 
like it The computer, on the other hand , always gives me 
a reason why Tm incorrect . Its a game l play with my 
Mac ... There are a bunch of rules and it tells me 
(usually via a bus error) that I broke one . 

— Konstantin Gthmer 

It s the one thing in my life that is easy to debug . 

— Michael Weingartner 

These last tw o hint at something else that I think might 
be important. In sharp contrast to the real world, the 
world of the computer is reassuringly knowable. What 
this means is that computer problems always have answers. 
There is always a discoverable reason behind a 
computer’s behavior, and I can’t help wondering 
whether this is one of the major reasons people get 
such satisfaction from programming. 


Most questions we ask about the real world turn out to 
be hopelessly complicated. How can we improve the 
economy? No neat and tidy answer to that one. Why 
does your child love those particular red plastic boots 
so much? That’s not really answerable in any complete 
way. Why is ice slippery? Why is the sky blue? How do 
birds know when itis time to fly south? None of these 
questions have clean answers. 

Ironically, though, there seems to be a basic human 
need to find answers. Look at die huge amount of time 
and energy we spend trying to discover and proclaim 
truths about our world. Religion, art, and science are all 
manifestations of the human desire to understand. So 
it’s no surprise that computers, with their fantastically 
complex but ultimately knowable behavior, are 
extremely satisfying artifacts to spend time grappling 
with. Finding the answers can be enormously 
challenging, but there’s always an answer to be found: 

It gives me one thing I *know * / can boss around . 

—Jim Luther 

Amen. 


RECOMMENDED READING 

* Dreams of Reason by Heinz R , Pagels [Simon and 
Schuster, 1988), 

* The Hidden Life of Dogs by Elizabeth Marshal) 
Thomas [Houghton Mifflin, 1993). 

* Tuesday by David Wiesner [Clarion Books, 1991). 
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Thanks to all the survey respondents and to Jeff Barbose, Michael 
Greenspan, Bill Guschwan, Mark (The Red") Harlan, Bo3b 
Johnson, Lisa Jongewaard, and Ned van Alstyne for their always 
enlightening review comments. * 


Dave welcomes feedback on his musings. He can be reached 
at JOHNSON.DK on AppleLink, dkj@apple.com on the Internet, or 
75300,715 on CompuServe." 
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DEBUGGING 


ON POWERPC 



DAVE FALKENBURG AND 
BRIAN TOPPING 


Debugging on a PowerPC processor-based Macintosh is just like 
debugging on any other Macintosh , only different You should bring 
along the debugging skills you carefully honed on 680 x 0 -based 
machines but expect the mechanics of debugging to be easier thanks to 
the PowerPC two-machine debugger ; We give you basic instructions 
and provide a sample program that you can crash like crazy while you 
learn to debug PowerPC code . 


The most important thing to realize when you set out to develop (and hence debug) 
for the PowerPC processor-based Macintosh is that this beast is still a Macintosh. 
Besides having a 680x0 emulator, the CPU has a Macintosh Toolbox in ROM, low- 
memory globals, a trap dispatcher, and 680x0 interrupt vectors. Since it retains so 
many dements you know and love, you don’t have to throw away any of what you’ve 
learned about debugging with MaesBug, TMON, or any other debugger. 

On the other hand, if all the new Macintosh had up its sleeve were 680x0 emulation, 
we wouldn’t be writing this article. As described in “Making the Leap to PowerPC” 
in develop Issue 16 and in the imminent Inside Macintosh: PowerPC System Software, the 
PowerPC runtime architecture is new and improved. A couple of new managers — 
the Code Fragment Manager and the Mixed Mode Manager — help bridge the 
software gap between the 680x0 emulator and the PowerPC 601 microprocessor, and 
introduce some new r twists and turns in how code is loaded and executed. 

This article introduces you to the two-machine debugger developed for debugging 
PowerPC code. It then lays down some debugging ground rules, describes the 
circumstances in which your program might end up in the debugger, and discusses 
extensions and dcmds old and new to assist you in debugging. Finally, it talks about 
how to debug even in the absence of the debugger nub. 

On this issue’s CD you’ll find CrashOMatic, a sample program you can use to explore 
the debugger without risking your own code. CrashOMatic is designed to cause 
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crashes or demonstrate unusual aspects of PowerPC debugging. When launching 
CrashOMatic, hold down the Control key to force the debugger to take control. 

To experiment with debugging CrashOMatic and to develop and debug native 
PowerPC applications* you'll need the Macintosh on RISC Software Developer's Kit 
(soon to be available from APDA) or one of the other PowerPC development kits 
available from third parties. The Macintosh on RISC Software Developer's Kit 
contains R2Db, an MPW-based cross-compiler called PPCC, and other assorted 
tools used for building PowerPC applications. 

INTRODUCING R2DB 

Apple's new debugger for the PowerPC processor—based Macintosh is called R2Db, 
for “RISC two-machine debugger.” (As this issue goes to press, the fate of dus name 
is undecided, so it may be different by the time you read this.) This modernized cross 
between ReAnimator and SourceBug allows for single stepping, setting breakpoints, 
and disassembling PowerPC code fragments. Like MacsBug, it's a systemwide lo^v- 
level debugger; unlike MacsBug, R2Db also enables source-level debugging and is 
designed for debugging PowerPC applications. But as we hinted at earlier, you 
probably don't want to throw away your MacsBug skills just yet. R2Db can be used in 
conjunction with MacsBug, as explained in the section “Working With demds and 
MacsBug.” 

THE TWO-MACHINE SCHEME 

R2Db is a two-machine debugger, as illustrated in Figure L The R2Db application 
runs on the host machine, which can be any Macintosh at all, preferably one with a 
large screen and enough CPU power to run a debugger built with MacApp 3.0. The 
part of R2Db called the PPC Debugger Nub runs on the target machine } the 
PowerPC processor-based Macintosh running the program you want to debug. The 
host machine acts as a remote control panel for the target. The machines need to be 
connected by a standard 8-pin printer cable. 

Using two machines to debug code has several advantages. For one, a bug in your 
application that locks up the keyboard can't bring your debugging to a halt. For 
another, you can debug interrupt-level code without having to have incredible luck. 
(Can you say “MacsBug caused the exception”?) Throughout the development of 
Macintosh with PowerPC, the system softw are team relied on R2Db to debug such 
nasty (but necessary) things as the Memory and Resource Managers. Running a 
single-machine debugger on such shaky ground can lead to premature aging and the 
loss of some motor functions. 

On the other hand, two-machine debugging has the disadvantage of requiring two 
Macintosh systems. (Oh darn, I guess it's time to ask the boss for another Macintosh 
Quadra.) Don't worry, though — Apple (and others) are busy working on single¬ 
machine debugging environments for those folks w r ho develop on smaller budgets. 
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Figure 1 

The Two-Machine Debugging Scheme 

R2DB BASICS 

When you first launch R2Db, it presents a Standard File dialog box from which you 
choose an xSYM file to use when debugging. If you’ve used Source Bug, you know 
that a SYM file bundles together information about die application’s source and 
object code and enables the debugger to associate a range of machine-language 
instructions widi a line of C source code. The xSYM file is an extended version of the 
MPW SYM file that supports both 680x0 and PowerPC code. To support debugging 
“lat” applications — those with both 680x0 and PowerPC versions packaged together 
—■ two different kinds of SYM files arc needed: the SYM file for the 680x0 version 
and the xSYM file for the PowerPC version. 

When a PowerPC application is being debugged at the source level, its xSYM file and 
all its source code must be available on the machine running R2Db. Without the 
xSYM file, your application can still he debugged, but not at the source level. 

When you choose an xSYM file, the R2Db browser window appears. This window, 
which will be familiar to users of Smalltalk or MacApp’s Mouser, enables you to 
examine source code by file and function. Choosing Go To Debugger from the 
Debug menu makes the browser window look like the one shown in Figure 2. In the 
top left corner, a list of source files is presented. When a source file is chosen, the 
functions belonging to that file are listed in die top right corner. (Sorry, C++ fans — 
there’s no object browsing in this release of R2Db.) The status of the target machine, 
along with a few stepping controls, appears in a control palette. 

A small arrow points to the current instruction or line of code being executed. 
Breakpoints can be set by clicking to the left of the source display; a small hexagonal 
“stop sign” marks any breakpoints you’ve set. Double-clicking a breakpoint enables 
you to choose from a myriad of useful variants on the traditional behavior. Finally, 
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Figure 2 

The R2Db Browser During CrashOMafic Debugging 


you can switch between assembly and source views by using the pop-up menu at the 
lower left of the display. To see exactly how the compiler translates your C code into 
native PowerPC code, select a line of source code and then switch to the assembly 
vi c w, wh e re i t’s hi gh I i gh ted. 

Lurking under the R2Db menu bar are some useful commands, including commands 
to get register displays, memory dumps, and even 680x0 disassembly. If you ever find 
yourself Stopped outside of your application, choose Show Instructions from the 
Views menu to get a disassembly at the current point of execution. This can also be 
helpful when debugging without an xSYM file. 

R2DB IDIOSYNCRASIES 

Like all things in life, R2Db has a couple of idiosyncrasies you should be aware of. 
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Debugger versus SysBreak. If you’re familiar with SADE and SourceBug, you’re 
probably accustomed to using SysBreak and SvsBreakStr to add high-level 
breakpoints to your code. These functions aren’t supported by R2Dh, so you should 
use the familiar Debugger and DebugStr calls that you would normally use with 
MacsBug or other low-level debuggers. If a PowerPC] debugger isn’t installed, these 
calls are routed to MacsBug for handling. If you prefer using MacsBug to inspect data 
structures or log debugging messages, you can use the functions Debugger68k and 
DebugS tr6 8k. 

Memory Manager access faults. Starting with the Macintosh Ilci, Apple added a 
hack to the existing Memory Manager to correctly support changes for 32-bit 
addressing and NuBus™ expansion cards. The change involved adding bus error 
wrappers within several internal routines to automatically call StripAddress and retry 
when a 24-bit handle is passed to the Memory Manager while the machine is 
temporarily operating in 3 2-bit mode. These bus error wrappers don’t exist on 68000 
machines like the Macintosh Plus, SE, and Classic (a fine reason to test your software 
on all sorts of machines). 

These handlers also mask a serious problem: fake handles, fake pointers, and fake 
heap zones being passed to the Memory Manager. For Macintosh with PowerPC, the 
Memory Manager has been completely rewritten and actually preserves this tolerant 
behavior —but with a twist. When any PowerPC debugger is installed, these 
Memory Manager exceptions gel routed through the debugger to point out the 
problem to the developer. 

We would have added a “feature” to CrashOMatic so that you could sec this behavior 
in action, but fortunately it doesn’t happen that often. Before examining the fields of 
a handle or pointer block, the Memory Manager checks a magic cookie in the block 
as a first guard against fake handles. If we were to contrive an example without setting 
that magic cookie, die HLock call would still return an error code as it should; we 
just wouldn’t see the bus error handlers get hit. 

There are, however, some applications in which you will see the bus error handlers 
get hit. Open a file in ResEdit 2.1.1, for example, and you’ll see access faults in 
R2Dh. Choose Propagate Exception from R2Db’s Control menu and the Memory 
Manager will clean up after ResEdit. 

In future versions of Macintosh system software, diis compatibility hack will be 
removed. Consider yourself warned. 

GROUND RULES FOR DEBUGGING ON POWERPC 

Before you start debugging your PowerPC application, you should commit the 
following ground rules to memory. This will ensure that you get off on the right 
foot. 
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Rule 1: Always use a nonoptimized build for source-level debugging. 

RISC C compilers radically reorder the sequence of instructions when generating 
optimized code. This makes straightforward source-level debugging impossible — 
imagine single stepping to the next line of code and having the arrow' move to a 
statement three lines before where you just w^ere. Following is a little program to 
demonstrate why you don’t want to do source-level debugging with an optimized 
build of your code unless you really know what you Ye doing. Ignore the fact that 
“dude” is never initialized before being used. 

void main(void) 

{ 

long counter, dude? 
float fooVal = 1.0? 

for (counter = 1? counter < 1000? counter++) 

{ 

fooVal = counter * fooVal; 
dude++? 

} 

> 

Below is the nonoptimized compiler output (Incidentally, we compiled this program 
using the IBM compiler; if you compile it with PPCC you’ll see different results.) 
Notice that the basic top-to-bottom structure of the C source is preserved. 

Main: 

stw r31,-4(SP) ?# Preserve nonvolatile registers (r31) 

stwu SP, -128 (SP) ;# Create stack frame 

;# Variable initialization starts here. 


Iwz 

r31,xx(RTOC) 

?# 

Get address of a 1.0 

stw 

r3,152(SP) 

?# 

Save r3 - we are going to use it 

Ifs 

fpl,0(r31) 


Put 1,0 in a register 

stfs 

fpl,56(SP) 

?# 

Put 1,0 into fooVal 

The FOR loop starts 

here. 

li 

r3,l 

ft 

Get a 1 

stw 

r3,60(SP) 

ft 

Put it in counter 

liu 

r4,r0,0x4330 

;t 

Make floating-point version of counter 


stw r4,96(SP) 

empi crl,r3,1000 ;# (counter < 1000)? 
bgt crl,Exit ;# Goto end of loop 
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;# Body of the FOR loop starts here. 
Loop: 


lwz 

r3,60(SP) 

;# 

Load counter into register 

lfd 

fp2,8(r31) 

;# 

Make fp version of counter from counter 

xoris 

r3,r3,0x8000 



stw 

r3,100(SP) 



lfd 

fpl,96(SP) 



f sub 

fpl,fpl,fp2 



f rsp 

fp2,fpl 



If s 

fpl,56(SP) 

;# 

Get fp version of counter 

fmul 

fpl,fpl,fp2 

ft 

fooVal = fooVal * fp version of counter; 

frsp 

fpl,fpl 



stfs 

fpl,56(SP) 



lwz 

r3,64{SP) 

;t 

dude++; 

addic 

r3,r3,l 



stw 

r3,64{SP) 



lwz 

r3,60(SP) 

;* 

counter++ 

addic 

r3,r3,1 



stw 

r3,60(SP) 



?# Conditional test of 

FOR 

loop here. 

empi 

crl,r3,1000 

;# 

if (counter < 1000) 

bit 

crl,Loop 

;i 

goto loop 

Exit: 




lwz 

r31,124(SP) 

;# 

Restore saved registers (r3I) 

addic 

SP,SP,128 

;# 

Release stack frame 

blr 


;# 

Outta here! 


The optimized compiler output is shown below. Note the interleaving of instructions 
used to initialize fooVah Also note the radically different loop structure, which has no 
straightforward correspondence to the C code — counter is now zero-based and 
decrements, fooVal is calculated in a totally different fashion, and dude is nowhere to 
be found in the generated code. 

Main: 


lwz 

r3,xxx(RTOC) 

} 1 

Get address of a 1,0 

li 

rQ,999 

l # 

counter = 999; 

lfd 

fpl,B(r3) 

} # 

Finish fooVal = 1.0; 

fmr 

fpO,fpl 

;# 

ttnp = fooVal 

mtspr CTR,r0 

;# 

CTR = counter 
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? # tmp = tmp + fooVal 

;§ CTR —; if (CTR 1= 0) goto loop 

;# Outta here I 


Loop: 

fadd fpO t fpO,fpl 

bdnz loop 

blr 


The moral of this story is that if you want to debug your application by looking at 
source code, you should create a special version compiled without optimization turned 
on. (Of course, the version you ship should be optimized*) If you can't cause the 
problem to occur with compiler optimizations turned off, you'll need to become 
familiar with debugging techniques involving animal or human sacrifice (or just learn 
to love reading optimized PowerPC assembly language). 

Rule 2: Enable generation of symbol information by the compiler. 

It's also important at build time to enable generation of symbol information by the 
compiler. This is analogous ro “-sym on" and “-mbg on" for 680x0. The extra 
information generated is used by the MPW tools Link and MakeSYM to create the 
xSYM file that R2Db uses to enable source-level debugging. Here's a makefile to 
build a simple PowerPC program using PPCC (with debugging extras in boldface): 


APPTSfAME = 
APPOBJECTS = 
PPCC 

PPCCQPTIQNS = 


CrashOMatic 

CrashQMatic.o 

PPCC 

-w conformance -appleext on -sym on -opt off 


PEFOPTIONS = -ft 1 APPL 1 -£c , GDed’ 

LIBEQUATES = -1 Inter faceLib,xcoff=lnterfaceLib 3 


-1 StdCLib,xcoff=5tdCLib 3 

-1 MathLib,xcoff=MathLib 

{APFNAME} // {APPOBJECTS} 

FFCLink -warn -sym on 3 

{APPOBJECTS} 3 

"{PPCLibraries}"Interfacelib.xcoff 3 

"{PPCLibraries} 11 StdCLib. xcof f 3 

"{PPCLibraries}"MathLib.xcoff 3 

" { PPCL ibr ar ie s }" S t dC Ru nt ime. o 3 

" {PPCLibraries }" pPCCRunt ime.o 3 

-o {APPHAME}.xcoff 


# Create PEF executable from linker output 

makepef {APPNAME}.xcoff -o {APPHAME} {LIBEQUATES} {PEFOPTIONS} 

# Rez in 'cfrg' (0) resource 
rez {APPWAME}-a -o JAFFNA*®} 

# Create xSYM file for debugging 
makesym -o {APPNAME},xSYM {APPNAME}.xcoff 
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CrashOMatic.o / CrashOMatic.c 

{PPCC} {PPCCGPTIGNS} CrashGMatic.c -o CrashQMatic,o 

Role 3: Always test with virtual memory both on and off. 

Macintosh developers have long been used to having free access to any bits in 
memory, whether they contain code, data, or teachings of the illummati, Meanwhile, 
users have been complaining that the Macintosh doesn’t offer “modem" features like 
protected memory. The first release of System 7 for the PowerPC microprocessor 
includes the ability to protect PowerPC application code from errant write 
instructions; however, write protection is enabled only when virtual memory is 
turned on. 

In addition, several PowerPC C compilers create string constants and initialized 
arrays in read-only sections by default. Modifying these values from your program 
will cause an access Fault. For instance, it’s surprisingly easy to write die following: 

DebugStr(C2PStr("Hello, world")); 

Because C2PStr modifies a string in place, your program will attempt to write into 
the read-only storage where “Hello, world” lives. There are compiler options to turn 
this feature off, hut we don't recommend them. 

The stricter runtime environment isn't the only reason to make sure that your 
software works properly w'hen virtual memory is active, PowerPC programs are 
usually larger than dieir 680x0 cousins, so the likelihood of a user’s enabling virtual 
memory on a PowerPC machine is much higher than on an earlier Macintosh. Apple 
has been telling you to be virtual-memory compatible for years. Just do it now and 
your customers will thank all of us later when Apple can release a protected-memory, 
preemptive multitasking version of the Macintosh operating system without breaking 
any of dieir favorite applications. 

Rule 4; Don't write self-modifying code. 

Unlike its later siblings the 603 and the 604, the PowerPC 601 has a merged data and 
instruction cache, which makes it much easier to write self-modifying code without 
getting caught. Remember all those 68040 compatibility problems you had when the 
Macintosh Quadra first came out? Don’t forget what you learned. Also remember 
dial writing to application code will cause an access fault in any PowerPC application 
w f hen virtual memory is active. 

Use the Code Fragment Manager to load all executable code. The Code Fragment 
Manager will take care of invalidating instruction caches (and Rushing data caches) in 
an efficient manner on later versions of the PowerPC chip. If you're one of those 
crazed folks w ho still w r ants to write “stracts” of code, custom-compiled shape 
blitters, or stub defprocs, be forewarned that you do so at your ow r n risk. 
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With the ground rules laid, it 5 s time to look at the reasons why your application 
might end up in the debugger, 

EXCEPTIONAL CIRCUMSTANCES 

Just like the 680x0, the PowerPC microprocessor has a list of things it can’t handle 
without the help of developers like you. Any program can come to a screeching halt 
as a result of any of the following exceptions, (Note chat these are hardware 
exceptions, as opposed to the software exceptions discussed in the article “Living in 
an Exceptional World” in develop Issue 11.) 

illegallnstructionException 

You executed some code that wasn’t code. This usually happens when you 
accidentally call 680x0 code without using Call Uni versalProc or one of its macro 
shortcuts. 

trapException 

A trap instruction that the debugger didn’t know about was encountered. The most 
likely cause is hitting a developer-inserted debug trap. 

accessException 

This PowerPC version of a bus error usually occurs when a memory access was made 
in never-never land. You might encounter the fabled address OxDEADBEEF in an 
access exception; someone (probably the same person who came up with the eieio 
instruction) decided it would he cool to initialize registers with this weird value to 
help you understand that you probably used an uninitialized variable. 


re adOnlyMemoryException 

As mentioned earlier, when virtual memory is active, application code is mapped 
read-only for your protection. You may also see this exception when errant PowerPC" 
code attempts to write to ROM. Sometimes this exception masquerades as a generic 
access exception, 

privilegeViolationException 

Remember how users wanted protected memory? Part of ensuring this capability in a 
future Macintosh is ensuring that nobody writes code that can mess with the 
operating system behind its back. Learn to live with it — the users who pay you want 
things this way. For a list of privileged instructions that you should avoid in your 
application, check out the PowerPC 601 RISC Microprocessor User's Manual, (By the 
way, even the debugger and the 680x0 emulator are written using only user-level 
instructions.) 
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Those interested in obscure hexadecimal 
numbers will wont to know that 0x7F800008 is 
the value corresponding to one of the many 
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traceException 

If the debugger goes astray, you may see this exception* It’s pretty tough to cause* 


In a departure from 680x0 Macintosh applications, PowerPC applications can 
attempt to field these exceptions before the dreaded bomb is emblazoned on the 
user's screen, without resorting to low-memory antics. Using the Exception Manager 
(new on the Macintosh with PowerPC) it's possible to catch memory faults, illegal 
instructions, and other faults within your application. 

If you encounter an exception inside R2Db and would like to give the application a 
crack at fixing things, you can choose the Propagate Exception command from the 
Control menu. With some work, it’s even possible to debug your application’s 
exception handler. 


USING OLD TRICKS IN THE NEW WORLD 

Experienced developers know that extensions (such as Double 'Trouble and Dispose 
Resource) and demds (such as rd, file, drive, and driver) make the job of debugging 
go much more quickly. Most of the existing MacsBug extensions and demds work in 
the PowerPC world much as you would expect, but you should be aware of a few 
caveats. 

WORKING WITH DEBUGGING EXTENSIONS 

Tried-and-true debugging extensions install 680x0 code that wall be emulated. When 
they detect a problem, they may behave differently depending on whether they're 
discipline-style extensions or memory-modification extensions. 

Discipline-style extensions are extensions that patch traps to check parameters to calls 
for validity. Since the code that patches into the trap is emulated and signals failure 
via a 680x0 DebugStr trap, MacsBug is entered during a failure. 

Memory-modification extensions such as EvenBetterBusError work by causing a bus 
error (also known as an access fault) in the problem program. You should remember 
that EvenBetterBusError w^orks by setting the value at location 0 to be an illegal 
instruction, an illegal address, and an odd address, all in one 4-byte value. This 
catches lots of programs that accidentally use stale data in empty' handles and nil 
pointers returned by NewPtr. 

Through the magic of emulation, EvenBetterBusError works as before for 680x0 
applications. Because EvenBetterBusError causes the problem to surface within the 
application (and not MacsBug), the bus error exception is thrown to the application's 
exception handler. If no exception handler is installed, control is passed to the PPC 
Debugger Nub. As with all PowerPC exceptions, if the debugger nub isn't installed, 
the PowerPC system software generates a 68000 “spurious interrupt” exception, 
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which is caught by MacsBug, Well cotne back to this in the section “Debugging 
Without the Debugger Nub/ 1 


WORKING WITH DCMD5 AND MACSBUG 

Because R2Db does have its shortcomings (mostly due to lack of maturity), it gives 
you a way to enter Macs Bug — by choosing Enter MacsBug from the Extras menu. 
This enables you to use almost any Macintosh debugging trick in the PowerPC 
world. You might want to do this, for instance, to gain access to commands that 
display data in forms not yet available in R2Db, For more information on how the 
old and new r worlds coexist in a compatible yet forward-thinking manner, see “Traps 
and the PowerPC InterfaceLib; More Than You Want to Know,” 

When in MacsBug, you need to remember that you got there as a restdt of a Mixed 
Mode transition to a 680x0 R2Db subroutine that contains a 680x0 DebugStr, and 
nothing more. You can look and touch, but you cank step. Stepping will only walk 
you into the hands of the Mixed Mode monster, returning control to the PPG 
Debugger Nub and upward to R2Db. It’s more dignified to return to R2Db when 
you choose to, by typing “G*” 

Be aware that the step-and-eheek commands such as step spy work only while the 
emulator is active. This is because they rely on 680x0 trace vectors or 680x0 
breakpoints. The emulator is good enough to oblige MacsBug when between 
emulated instructions, but remember that the PowerPC microprocessor pays no 
attention to such things* This changes the definition of these commands from “do 
neato thing you really like after each instruction” to “do neato thing you really like after 
each 680x0 instruction.” The difference is subtle but important, as illustrated by the 
following example* 

Choose Step Spy from the Debug menu in CrashOMatic; this will bring up a dialog 
w here you can type an address to spy on. Then choose Clobber from die Debug 
menu, which will bring up a dialog in which you type the same address. MacsBug will 
know r that the memory got hit, but it won’t know who hit it. Since the subroutine that 
did the clobbering and everything else back out to the main event loop is PowerPC 
code, the step spy won’t get hit until the next call to the emulator (usually a Toolbox 
trap), in this case WaitNextEvent, You may be thinking, “Funny, it looks like theres 
no way that the previous instruction could have done that much damage,” but 
remember that a lot of PowerPC code could have executed in the meantime. 

Another funny thing about the 680x0 emulator is the way in which trap dispatching is 
performed for emulated code* To gain an immense performance boost, if the 
emulator recognizes that the A-line exception vector points at the ROM trap 
dispatcher, it takes some shortcuts and runs its own superfast version. Unfortunately, 
doing an atb in MacsBug modifies this behavior and throws the emulator into low 
gear. Just for fun, try’ doing an atb _Chain (a trap that never gets called) and see how 
much your machine slows down. 
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You can port MacsBug demds to the 

PowerPC platform very easily. For more 
information, check out the R2Db documentation 
that accompanies the Macintosh on RISC 
Software Developer's Kit. * 


R2Db session, sometimes the connection between 
host and target can be dropped. The connection 
con usually be reestablished by relaunching R2Db 
on the host machine. * 


When you use MacsBug From within an 
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TRAPS AND THE POWERPC INTERFACEUB: MORE THAN YOU WANT TO KNOW 


Why would you won! to use MacsBug and R2Db at the 
same time? As mentioned earlier, Macintosh with PowerPC 
still has the familiar A-line trap dispatcher present on 
earlier Macintosh models. With the advent of system- 
supported shared libraries, it may seem strange to still 
support the trap dispatcher. Two main reasons motivated 
the use of the trap table by the PowerPC native toolbox: 
support should be provided for systemwide patching to 
preserve compatibility with existing System 7.x-friendly 
system extensions; and existing 680x0 software should be 
able to access PowerPC-accelerated Toolbox managers 
like QuickDraw, 

Toolbox accelerations such as PowerPC QuickDraw are 
implemented by using NSetTrapAddress to patch out the 
680x0 implementation with a PowerPC subroutine 


wrapped by a Mixed Mode routine descriptor. This allows 
existing 680x0 software to call PowerPC code in an 
application-transparent fashion. 

On the other side of the coin, PowerPC applications must 
be able to coll patchable versions of the Macintosh 
Toolbox, This is accomplished by building an interface 
library that calls through the trap dispatch table via 
CallUniversalProc, as illustrated below. 

Understanding the behavior shown in the illustration is 
useful for debugging now, but in the Future several new 
managers will be released that don't use this bizarre 
mechanism (most notably QuickDraw GX and the Thread 
Manager). For future compatibility, don't rely on this 
behavior. 


PowerPC application 



Widget ** GetWidget 
< 

return (NewH; 

> 

:Storage(void) 

indie(sizeof(Widget))); 




Interface library i 



Handle NewHandle(Size s) 
{ 


return CallUniversalProc (kHewHandleProcInfo, 
GetToolboxTrapAddress{ _NewHandle), s); 

> 


l 


Trap dispatcher 











NewHaodle 


- 






Memory Manager 


* 



p roc info 

J* 

Code pointer 

-■>■ 


infspr rQ,LR 
stwu rl,-72(rl) 





procPtr 

TOC pointer 



* * . 










blr 









Routine descriptor Transition vector 
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Speaking of atb, the way PowerPC code calls Macintosh traps makes this dcmd 
almost useless for PowerPC debugging. Remember that atb works by replacing the 
ROM trap dispatcher with its own version, but because all PowerPC calls to the 
Toolbox are invoked via Mixed Mode and not the 680x0 emulator trap dispatcher, the 
new r dispatcher is never invoked. Unfortunately, the same is true for atr. Fortunately, 
there is a fix for this in the form of a new dcmd. 

NEW EXTENSIONS AND DCMDS 

So far weVe looked only at extensions and Macs Bug dcmds created for die 680x0 
environment. As you'd expect, many more have been created for debugging the 
changes that came with the PowerPC technology. In this section we look at some of 
the most important ones. These dcmds were created by the PowerPC development 
team to aid in the construction of Macintosh with Pow erPC and are provided on this 
issue's CD in a completely unsupported and barely documented fashion. If they 
weren’t so useful, the people in charge probably wouldn’t let ns give them to you. 

atbv 

Given a trap name, atbv sets a breakpoint on the trap vector so that bodi emulated 
and PowerPC callers can be intercepted by the debugger. Unlike atb, it doesn't 
Ignore PowerPC callers or affect the emulator's ability to run at hill speed. 

brp 

The dcmd brp stands for “breakpoint PowerPC, 1 ' Given an address, brp will set a 
onc-tiine breakpoint at the address in R2Db, Unlike br, its 680x0 cousin, the 
breakpoint set by brp is cleared once it's been hit. 

cfm 

All code must he loaded by the Code Fragment Manager before it can be executed. 
The dcmd cbit displays the Code Fragment Manager contexts of loaded PowerPC 
code and is thus a very - powerful way to find exactly where an address lives. This 
dcmd is case sensitive. 

Typing "cftn” all by itself gives a dump that looks like this: 

CFM Info for all loaded fragments: 

context ID = 3: heapZone = 0G4cbeDG processName = "DiaTim 11 
connID=3: 'DiaTim T #0; file (v=-l,d=232) "DiaTim* @ 0:#12592 

inf = 'peff','pwpc', sym - #0, use - 1, pef = 004cdd£0, fig = 20 
sect 0: 8 OO4ce3aO-OO4dOe70 f exec, use = 1, len - #10968 

sect li I 004d36eO-Q04d624Q, writ, use = 1, len = #11104 

connID=4: 1 InterfaceLib f 10; inMem § 4D9f3690:#214592 

inf = 'peff 1 , 'pwpc*, sym = #2466, use = 1, pef = 409f369G, fig - 00 
sect 0: @ 40aO3ac0-40a268ec, exec, use - 2, len = #142892 

sect Is @ Q0Q143cQ~00Glb744, writ, use = 2, len = #29572 
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The entire dump shows many more libraries. All loaded code fragments, including 
shared libraries and applications, are listed. Every application running, whether 
emulated or PowerPC code, is provided with a Code Fragment Manager context ID. 
Individual code fragments, which include the application itself and any referenced 
shared libraries, are loaded into this context. The listing above shows that the 
application DiaTim has a code fragment context ID of 3, has a single executable 
(exec) code section and a writable (writ) data section, and references a shared library 
called InterfaceLib. 

Typing “din” followed by a name will dump the code fragment with that name, plus 
the libraries it references. Remember that PowerPC applications arc fragments, so 
this is quite useful for seeing only the fragments associated with your program. (In 
this example and the others that follow, what you type is shown in italic.) 

cfin DiaTim 

CFH Info for fragment named "DiaTim" 

context ID - 3; heapZone - 004cbe00 processName - "DiaTim" 
connID=3; ’DiaTim’#0; file (v=-I,d=232) "DiaTim" 0 0:#12592 

inf = ’peff',' pwpe V, sym = #0, use = 1, pef = 004cddfG, fig = 20 
sect 0; @ 004ce3a0-004d0e78, exec, use - 1, len = #10968 
sect 1: @ 004d36e0-004d6240, writ, use = 1, len = #11104 


dis 

The demd dis is like il for PowerPC] instructions. Given an address that points to 
code, dis disassembles the PowerPC] instructions at that address. 


dis 409cdf28 


409cdf28 

mf spr 

rO,LR 

| 7cQ802a6 

4Q9cdf2c 

stwu 

SP,OxffffffcO(SP) 

I 9421ffcO 

409cdf30 

stw 

rO,0x48(SP) 

| 90010048 

409cdf34 

ori 

r6,r3,0x0000 

I 60660000 

4Q9cdf38 

addis 

r4,r0,0x0003 

| 3C8000Q3 

409cdf3c 

add is 

r0,r0,0x0001 

| 3c000001 

409cdf40 

addic 

r4,r4,0x3932 

| 30843932 

drd and pp 





The demds drd and pp are used to examine the contents of a Mixed Mode routine 
descriptor. The drd demd, which stands for “display routine descriptor,” is used to 
examine how a given trap is patched with PowerPC code, 

drd NewHandle 
drd: 00Q64ad0 

MixedModeMagic: OxAAFE, version: #7, flags: 0x00 (Notlndexable) 
loadLoc: 0x00000000, reserved2: 0x00000000, Selectorlnfo: 0x00 
(No Selector) 
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Routine Count (zero-based); 0x0000 (#0) 

- Routine Record 0x0000 (#0) at 0x0GG64adc - 

Proclnfo: 0x00033132, Reservedl; 0x00000000, ISA: #1 (PowerPC) 
Record Flags: 0x0004 (Absolute, IsPrepared, NativelSA, 

PassSelector, IsKotDefault) 

ProcPtr: 0x00064458, offset: 0x00000000, selector: 0x00000000 

Included in this information about the routine descriptor is the proclnfo value, which 
describes the calling conventions, and the procPtr, which is the address of a transition 
vector. Using pp, which stands for “parse proclnfo,” we can convert a proclnfo value 
into a more readable form. 

pp 33132 

Proclnfo: 00033132 


Calling Convention; 0x02 (#2) Register Based 
Return value: 4 Bytes in Register A0 
Parameter 1: 2 Bytes in Register PI 
Parameter 2: 4 Bytes in Register DO 

Finally, we can use our old friend dis to look at the code, remembering that a 
PowerPC procPtr is a pointer to a pointer to code (hence the extra caret in the 
following). 

dis 64458* 


40a9cb24 

mf spr 

rO,LR 

| 7c0802a6 

4Ga9cb28 

stmw 

r26,0xffffffe8(SP) 

I bf41ffeB 

40a9cb2c 

stw 

r0,0x8(SP) 

| 90010008 

4Qa9cb3Q 

stwu 

SP,0xfffffe90(SP) 

| 942Ife90 

40a9cb34 

Iwz 

r30,0x0{TOC) 

j 83c2G0GG 

40a9cb38 

rlwinm 

r29,r3,0,16,31 

j 547d043e 

40a9cb3c 

addle 

r6,SP,0x004c 

j 30clGO4c 


findsym 

Typing “findsym” followed by a symbol name gives specific information about an 
exported symbol. 

In the following example, we see that NewHandle lives in ROM at address 4Qa0d5dQ 
(your results will vary), has a TOC value of lh704, and occupies the shared library 
called InterfaceLib. 

findsym NewHandle 

findsym: "NewHandle” 

"NewHandle* 1952 TVec 00015f 10 (40a0d5d0,0Q01b704 ) in "InterfaceLib 1 ’ (1,4) 
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frown 

The dcmd frown, which stands for “fragment ownership,” is similar to wh in 
MacsBug hut is used to display the code fragment and closest exported routine name 
associated with a given address. Unlike wh T frown doesn't give yon any information 
about where an address is located within a Memory Manager heap. 

frown 40a0d5d0 

frown: 40a0d5d0 

is owned by: section #0 (exec,non-writ) of "InterfaceLib" 
is near: "KewHandle” #952 TVee 00015fl0 {40a0d5d0,000!b7Q4) 


r2db 

The dcmd r2db allows you to enter R2Db from MacsBug. It’s the complement of 
R2Dh 5 s Enter MacsBug command. But because Enter MacsBug executes a 
_Debugger trap, it isn’t the greatest idea to use r2db as a way of getting back to 
R2Db — MacsBug and R2Db aren’t reentrant in all cases. Instead, the best way to 
get back to R2Db is by typing a simple “G” in MacsBug, 

scp 

The dcmd scp stands for “stack crawl PowerPC.” Given an address, it will unwind 
PowerPC stack frames to display a calling sequence. This dcmd doesn’t understand 
Mixed Mode sw itch frames, so it may not prove useful in the general case. 

tdp 

The dcmd tdp stands for “total dump PowerPC.” Much like its MacsBug sibl ing td T 
tdp displays all the registers from the PowerPC context. This is useful for looking at 
a crash when the PPC Debugger Nub isn’t installed. 

DEBUGGING WITHOUT THE DEBUGGER NUB 

Believe it or not, you can remove the PPC Debugger Nub and still debug your code. 
While this isn’t the optimal debugging environment, you may find yourself in it in 
the future, and it’s good to be prepared. 

The basic problem is to understand the context that the unhandled native exception 
will put you in, what values are a good reflection on the native execution context, and 
how to reconstruct what happened in your mind. 

Remove the debugger nub from your System Folder and reboot. Then launch 
CrashOMatic and choose the Bus Error command from the Debug menu. This will 
drop you into MacsBug with a spurious interrupt. MacsBug has no idea what a 
PowerPC exception frame looks like and makes this not-so-great guess as to the 
cause of your problem. 
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Starr the attack by looking at the native context. (Yon may need the PowerPC 601 
RISC Microprocessor User's Manual handy if you haven't done much of this yet.) Type 
“tdp” to get a dump that will show r you the context of the native machine. 

Spurious Interrupt or Uninitialized Interrupt Vector at 00643762 
while fetching instructions from FFFFFFFE and 00000000 while reading 
word from 20104802 in F 


tdp 

PowerPC registers from context block 


PC 

= 

08c877e0 

LR 

= 

08c87cf0 

CR 

= 

24000004 




CTR 

= 

409EEE18 

XER 

= 

20000010 







rO 

= 

000225F8 

r8 

= 

08CA4908 

r!6 

= 

00000000 

r24 

- 

00000000 

rl 

- 

08D93DDA 

r9 

- 

00000000 

rl7 

= 

00000000 

r25 

= 

4Q9DF150 

r2 

- 

00022904 

rlO 

- 

0003AB30 

rlB 

= 

46810000 

r26 

= 

00133002 

r3 

= 

deadbeef 

rll 

= 

409EEE18 

r!9 

= 

00000000 

r27 

= 

00000002 

r4 

= 

deadbeef 

r!2 


6802D764 

r20 

= 

00000000 

r28 

= 

G8D93DDA 

r5 

= 

68FFF740 

rI3 


68FFF400 

r21 

s 

00000000 

r29 


0008C838 

r6 

= 

00000000 

rl4 

= 

00000000 

r22 

= 

48400000 

r30 

= 

0008C82C 

r7 

= 

08CA4808 

rl5 

- 

00000000 

r23 

- 

00000000 

r31 

= 

68FFF740 


The PowerPC runtime environment specifies that R1 is used as the stack pointer and 
that the return address is kept inside the link register, LR. If w'e dis at the PC, w r e can 
see that we’re inside the routine doWithoutProtection, 

dis 8c877e0 

doWi thoutFr otec t ion-J-3 4 


+ 0034 

08c877eO 

Iwz 

r5,0x0(r4) 

| S0a40000 

+0038 

08c877e4 

stw 

r5,0x3c(SP) 

| 90al003c 

+QQ3c 

08c877e8 

b 

doWithoutProtection+58 

| 4800001c 

+0040 

08c877ec 

lha 

r6,Qx5a(SP) 

| a8clQ05a 

+0044 

08c877f0 

crtipi 

0,r6,0x0005 

| 2C06D0D5 

+0048 

08c877f4 

be 

BO IF, CRO EQ,doWithoutProtection+20 

| 4182ffd8 

+G04c 

08c877f8 

lha 

r7,0x5a(SP) 

| a8el005a 

+0050 

08c877fc 

empi 

l,r7,0x0004 

j 2 c S 7 0 0 0 4 

+ 0054 

08c87800 

be 

BO IF,CR1 VX,doWithoutProtection+30 

| 4186ffdc 

+ 0058 

08c87804 

Iwz 

rO,0x48(SP) 

| 80010048 

+ 005c 

08c87808 

addle 

SP,SP,0x0040 

j 30210040 

+ 0060 

08c8780c 

mts 

LR, rO 

j 7c0S03a6 

+ 0064 

08c878l0 

bclr 

BO ALWAYS,CRO 

j 4e80002D 


Of course, it’s pretty easy to debug a rigged example, but nonetheless it’s a valuable 
experience to get practice reading hex dumps of PowerPC stack frames inside 
MacsBug, This actually has some historical significance, in that many folks (in the 
original generation of programmers) debugged problems almost exclusively through 
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large printed stacks of octal numbers known affectionately as “dumps/ 1 Now a new 
generation of hackers can learn how difficult life was when their bosses not only 
programmed with toggle switches but also had to walk to school through a 
snowstorm, uphill —both ways. 


NOW BUG OFF! 

For more interesting examples of hybrid debugging, check our the Debug menu in 
CrashOMatic. Included at no extra charge are examples of using the PowerPC 
Exception Manager to do strange and exciting things with your program. We hope 
that these hints and techniques will help you debug your PowerPC application in less 
time than it took us to write this article. 
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JOHN WANG 


SOMEWHERE IN 
QUICKTIME 

CROSS-PLATFORM 
COMPATIBILITY AND 
MULTIPLE-MOVIE 
FILES 


The success of QuickTime since its introduction in 
December of 1991 has been extraordinary; not only are 
there now countless applications and multimedia 
products for QuickTime on the Macintosh platform, 
but QuickTime has been successful for cross-platform 
developers as well. QuickTime for Windows, shipping 
since November of 1992, is becoming an important 
tool for Windows multimedia developers. Because 
movies can be created with QuickTime on the 
Macintosh and then used unaltered with QuickTime 
for Windows, developers are able to create a movie 
once and use it on both systems. This capability has 
been available since the 1.0 release of QuickTime. 

To satisfy your curiosity and help you out w ith your 
own QuickTime products, this column discusses how 
to create movie files that are cross-platform compatible 
and then gives techniques for storing and accessing 
multiple movies in a single file (which currently poses 
a problem in the cross-platform environment). 

CREATING CROSS PLATFORM-COMPATIBLE 
MOVIE FILES 

T he structure you choose for your QuickTime movie 
files wall depend in part on the platform your movies 
will, run on. This is because the Macintosh file system is 
different from other file systems in that there can be up 
to two forks in every file: a data fork and a resource 
fork. The data fork is the standard file for I/O that 
most file systems support. The resource fork, however, 


is unique to die Macintosh. It’s a “database” of 
resources that can be randomly accessed via the 
Resource Manager. 

There are two components to a movie file: the movie 
resource atom — a small data structure describing the 
movie, its tracks, and the tracks’ media — and the 
movie data atom , containing the movie’s data such as 
video and sound. A typical movie file on the Macintosh 
consists of a movie resource atom in the resource fork 
and a movie data atom in the data fork. Storing the 
movie resource atom in the resource fork with resource 
type 'moov allows easy random access to the data it 
contains. The movie data atom is stored in the data 
fork as sequential data, which optimizes playback 
performance. 

Because file systems on other platforms don’t support 
a resource fork, a movie that is to be used on other 
platforms must have its movie resource atom stored in 
the data fork of the movie file. This type of file is called 
a single-fork file because the movie resource atom and 
the movie data atom are both stored in the data fork of 
the movie file, and the resource fork is not used. 

Movies that w ill be played on both Macintosh and non- 
Macintosh platforms can use a file in which the movie 
resource atom is redundantly stored in both the 
resource fork and the data fork of the file. The movie 
data atom is, as always, stored only in the data fork. For 
lack of a better term, this type of file is also often called 
a single-fork file since the resource fork of the movie 
file can be ignored. 

The simplest way to create a single-fork movie file for 
cross-platform compatibility is to use the Movie 
Converter application from the QuickTime Starter Kit 
(available from Apple-authorized dealers). The Save As 
dialog in this application has a checkbox that allows a 
movie to be stored in the single-fork format. However, 
the QuickTime API can easily be used to add this 
capability to any application. You simply call either 
FlattenMovie or FlattenMovieData with the 
flattenAddMovieToDataFork flag set. When called 
with this flag set, FlattenMovie places the movie 
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resource atom in both forks, while FlattenMovieData 
puts it only in the data fork, leaving the resource fork 
untouched. 

Movie files that are created with FlattenMovie or 
FlattenMovieData with the AattenAddMovieToDataFork 
fiag set are compatible with both QuickTime and 
QuickTime lor Windows because QuickTime is able to 
retrieve the movie resource atom and die movie data 
from the data fork alone on either platform. 

MULTIPLE-MOVIE FILES FOR THE MACINTOSH 

We’ll return to cross-platform issues in a moment, but 
first let’s take a look at the simple case of multiple- 
movie files: those that will be used only on the 
Macintosh platform. You can create such files in one 
of two ways, depending on whether you want the 
resulting file to be self-contained (that is, to contain all 
of the movie information in one file). Both of these 
methods have dieir benefits and drawbacks. The one 
that will work best for you depends on your 
implementation and performance testing. 

To create a self-contained multiple-movie file for the 
Macintosh, you can use the FlattenMovie call (without 
the flattenAddMovieToDataFork flag set) to append an 
entire movie to an existing movie file. This adds the 
movie resource atom to die resource fork and the 
movie data atom to the data fork of the file. 

The second method creates a multiple-movie file that’s 
not self-contained, but instead consists entirely of 
movie resource atoms that reference other movie files 
containing the movie data atoms. This technique can 
he useful if, for example, yoii’re writing an interactive 
CD application that uses multiple movies and you want 
to store all die movie resource atoms in a single file 
that’s relatively small. This file can be copied locally 10 
a hard disk for faster access. The drawback of this 
approach is that you have to handle multiple files 
rather than have everything in one file. The excerpt 
below from die sample code provided on die CD 
demonstrates — without error checking, for better 
readability —- how easy it is to add an existing movie’s 
resource atom to a movie file. 


// Open source movie file to add, 

OpenMovieFilef &reply«sfFile, &sourceRefNum, 
fsRdWrPerm); 

NewMovieFromFile(& theMovie, sourc eRe fNum, 

&resld, movieName, 0, (Boolean *) 0); 
CloseMovieFile(sourceRefHum}; 

// Write out to the collection file* 
currentResFile = CurResFile(); 

UseResFile(collectionRefNum); 
myResId - 0; 

AddMovieResource(theMovie r collectionRefNum f 
SmyResId, movieName); 

UseResFile(currentResFile); 

// Clean up* 

DisposeMovieftheMovie ); 

AddMovie Resource does more than just add the movie 
resource atom: it updates die data references so that the 
new movie will refer to the correct movie data file* 

Accessing multiple-movie files for Macintosh-only use 
is easy* You just use the Resource Manager to access the 
movie resource atoms in the resource fork of the file. 
The following excerpt from the sample code on the 
CD uses the Resource Manager to access the various 
movies. (The code on the CD adds the resource names 
of all the movies to a menu; your code can of course do 
whatever it wants with the movies.) 

currentResFile - CurResFile(); 

UseResFile(theRefNum); 

movieCount = Count1Resources(‘moov'); 

for (i=l; ic^movieCount; i++) { 

movieResource - GetllndResourcef‘moov’, i); 

// Do whatever you want with this movie* 

ReleaseResource(movieResource); 

UseResFile(currentResFile ); 

CROSS-PLATFORM MULTIPLE-MOVIE FILES 

To create a multiple-movie file that’s cross-platform 
compatible, you just repeatedly call FlattenMovie or 


For information on movie resource formats, see 

Chapter 4 of Inside Macintosh: QuickTime * 
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FI a ttenMovieDa ta vvi th th e flattenAddMovieToDa taFork 
Hag set, as described earlier under “Creating Cross 
Platform-Compatible Movie Files,” Accessing such a 
file, however, is complicated. Since it’s a single-fork file, 
you can’t access the movie resource atoms randomly as 
%vith the Resource Manager, There’s also a problem 
with accessing the atoms directly; to understand this 
problem, you need to know how a single-fork movie 
file is structured. 

The movie data atom appears before the movie 
resource atom in a single-fork file. The first four bytes 
of the movie data atom contain the size of the atom. 
(Figure 4-2 in Inride Macintosh: QuickTime, page 4-5, 
illustrates this structure.) This permits QuickTime to 
skip over the movie data atom to find the movie 
resource atom. If you place several movies in the same 
file, the movie data atoms are interleaved with the 
movie resource atoms. 

Here’s the problem: A bug in QuickTime through its 
current version (1.6.1) causes the size field in the movie 
data atoms to be filled in incorrectly The illustration 
below shows how QuickTime currently creates a 
single-fork movie file in which FlattenMovieData has 
been called multiple times. The atom size in the first 
movie data atom takes you to the last movie resource 
atom rather than the first movie resource atom. 
Therefore, you can locate only the last movie in the 
file. 


Atom size oF first 
movie doto atom 
encompasses all 
bat the last movie 
resource atom. 



Movie data atom 



Movie resource atom 



Movie data atom 



Movie resource atom 



Movie doto atom 



Movie resource atom 



. These movies 
cannot be 
foca fed. 


This bug will he fixed in the next version of QuickTime. 
The solution for now is to use the wrapper function 
called BetterFlattenMovieData, included on this issue’s 
CD. This function, when cal let! multiple times, creates 


a single-fork file in which the size and type fields of all 
atoms contain the correct information. 

To locate the movies in a file with correct size and type 
fields, you traverse the data fork and read in those fields 
of each atom to determine its size and whether it’s a 
movie resource atom. When you know the size of the 
atom, it’s easy to skip over it and access the next atom. 
Of course, the last atom is reached when the end of the 
file is reached. The following code from the CD 
demonstrates how you would do this, 

// Locate the file offset of the movie resource 
// atom stored at the specified index, 
if (FSpQpenDF(theFile , fsRdFerm, &myRefNum) 

== noErr) { 
currentLoc = 0; 
doneCounter - index; 

*fiieOffset - 0; 

while ((doneCounter >0)) { 

if (err - SetFPos(myRefNum, fsFromStart, 
currentLoc)) 
return(err); 
readLength = 8; 

if (err = FSRead(myRefNum, &readLength, 
header)) 
return(err); 

if (header[l] = 'moov 1 ) 
doneCounter—; 

*fileOffset = currentLoc; 
currentLoc += header[Q]; 

1 

FSClose(myRefNum); 

> else 

return (err); 
return (noErr); 

MOVING ON 

I’m happy to see that QuickTime is being used in new 
and exciting ways. By taking full advantage of the 
cross-platform and multiple-movie capabilities of 
QuickTime, you can bring your products to new 
heights. The sample code on the CD will start you on 
your way. Enjoy! 
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CONCURRENT 


PROGRAMMING 
WITH THE 
THREAD 
MANAGER 



ERIC ANDERSON AND 
BRAD POST 


Let us introduce you to the latest addition to the Macintosh Toolbox — 
the Thread Manager .: The Thread Manager enables concurrent 
programming so that you can provide true multitasking within your 
application. We give a quick overview of the Thread Manager and then 
move on to discuss advanced programming techniques not found in the 
‘Thread Manager documentation. 


The Thread Manager is a new part of the Macintosh Toolbox that provides both 
cooperative and preemptive threads of execution within an application. Although it's 
available only within your application and is not used for systemwide preemption, 
you can take advantage of it in many valuable ways: 

* Use a threaded About box so that your application can continue 
running in the background while displaying a modal dialog. 

* Do anything you do today at idle time with null events within a 
thread. This avoids die complexity of writing idleProcs, 

* Decouple time-consuming processes from the user interface of 
your application. For example, create an image-rendering thread 
for each image to render, and use the main thread for the user 
interface of the application. Similarly, with graphics screen redraws 
and print spooling, have a thread do the redraw or spool a print 
job w hile the main thread handles the user interface, 

* Construct complex simulations without complex logic. For 
example, in a program that simulates city streets, use a thread for 
each car, one for each traffic signal, and one for the time of day, 

* Use threaded I/O and communication to easily allow an 
application to act as both a client and a server. With this approach, 
applications can handle incoming questions and wait for incoming 
answers simultaneously Examples of this are discussed in more 
detail in “Threads on the Macintosh” in develop Issue 6, 


ERIC ANDERSON has been developing various controlling live-action effects (read: pyrotechnics) 
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The Thread Manager lias all the rights and privileges of other services in the 
Macintosh Toolbox, such as a trap interface to avoid linking a library into your code 
and header files for C, Pascal, and assembly-language programmers. Its a hilly 
supported product and will be around for years to come. You can license the Thread 
Manager through Apple’s Software Licensing group (AppleLink SW.LICENSE). 

The Thread Manager works on all Macintosh platforms running System 7 or later. 

THREAD MANAGER OVERVIEW 

This section describes the two types of threads — cooperative and preemptive — and 
the basic services for creating, scheduling, and deleting threads and gathering thread 
status. It also discusses the main thread, code organization, and thread disposal. 

COOPERATIVE THREADS 

Cooperative threads allow cooperative multitasking. TheyYe the easiest to use in terms 
of scheduling and accessibility to Toolbox traps. Everything you can do today in a 
standard application you can do with a cooperative thread — memory allocation, file 
I/O, QuickDraw, and so on. Cooperative threads yield to other cooperative threads 
only when the developer explicitly makes one of the Thread Manager yield calls or 
changes the state of the current cooperative thread. 

Cooperative threading in the Thread Manager is similar to the cooperative threading 
in the Threads Package made available through APDA a few years ago (see “Threads 
on the Macintosh” in develop Issue 6). In fact, this library should no longer be used 
since the Thread Manager is replacing it as the preferred method. Converting your 
applications from the Threads Package to the Thread Manager is easy as long as you 
don’t rely heavily on the internal data structures provided by the Threads Package. 
The big advantage to using the Thread Manager is that thread stacks are register 
swapped, not block moved, during a context switch. 

PREEMPTIVE THREADS 

Preemptive threads allow true multitasking at the application level. Whenever the 
application gets time from the Process Manager, preemptive threads for that 
application are allowed to run. Unlike cooperative threads, which execute only when 
a previously running cooperative thread explicitly allows it, preemptive threads may 
interrupt ihe currently executing thread at any time to resume execution. You can 
make th e p re e mpti ve th re a d y i el d back u > i h e j ust-p ree mpte d coope ra ti ve th re a d widi 
any of the Thread Manager yield calls. Alternatively, a preemptive thread can simply 
w ait for its time quantum to expire and automatically yield back to the cooperative 
thread it interrupted. If the interrupted cooperative thread is in the stopped state, the 
next available preemptive thread is made to run. Preemptive threads then preempt 
each other, in a round-robin fashion, until the interrupted cooperative thread is 
made ready. Figure f illustrates the default round-robin scheduling mechanism for 
threads. 
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Coopera rive thread 
of executable code 



Figure 1 

Round-Robin Scheduling Mechanism 


For situations where you don't want a thread to be preempted, the Thread Manager 
provides two calls for turning off preemption (see the next section). These calls don't 
disable interrupts, just thread preemption. 

Because a preemptive thread can usually “interrupt” cooperative threads and doesn't 
need to explicitly use the API to yield to other threads, preemptive threads have to 
conform to the guidelines set up for code executed at interrupt time. Don't make any 
calls that are listed in Inside Macintosh X-Ref Revised Edition, Appendix A, “Routines 
That Should Not Be Called From Within an Interrupt.” No moving of memory is 
allowed and definitely no QuickDraw calls should be made, QuickDraw calls may 
seem tempting and may even appear to work, but they fail on many occasions and can 
corrupt other parts of memory in subtle ways that are very difficult to debug. 
(QuickDraw GX was designed to be reentrant, so preemptive i breads may make use 
of the QuickDraw GX feature set if they follow the rules set up by QuickDraw GX.) 
If there’s only one thing you learn in this article, make sure it’s this; preemptive threads 
must follow interrupt-time rules! 

THE THREAD MANAGER API 

There are several data types declared in the Thread Manager APT that determine the 
characteristics of a thread. T hese include the type of thread you’re deal ing w ith 
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(cooperative or preemptive), the state of a thread {running, ready, or stopped), and a 
set of options for creating new threads. With the thread creation options, you can 
create a thread in the stopped state (to prevent threads from beginning execution 
before you want them to), create a thread from a preallocated pool of threads (which 
is how you would create a new thread from a preemptive thread), or tell the scheduler 
not to save FPU state for the new thread (to reduce scheduling times for threads that 
don't use the FPU). These creation options are combined into one parameter and 
passed to the routines that create new threads. 

General ^purpose services make it possible to create a poo! of preallocated threads and 
determine the number of free threads in the pool, get information on default thread 
stack sizes and the stack currently used by a thread, and create and delete threads. 

There are basic scheduling routines for determining the currently running thread and 
for yielding to other threads. You can also use the preemptive scheduling routines — 
ThreadBeginCritical and ThreadEndCritical — to define critical sections of code. A 
critical section of code is a piece of code that should not be interrupted by preemptive 
threads — because it’s changing shared data, for example. The use of critical sections 
of code is needed to prevent interference from other threads and to ensure data 
coherency within your code. Note that preemptive threads run at the same hardware 
interrupt level as a normal application, anti at Us to ThreadBeginGritical don’t disable 
hardware interrupts; they simply disable thread preemption . 

Advanced scheduling routines enable you to yield to specific threads and to get or set 
the state of nearly any thread. (You can't set a thread to the running state or change 
the state of the currently running thread if its in a critical section of code.) Custom 
context-switching routines allow you to add to the default thread context and may be 
associated with any thread on a switch-in and/or switch-out basis. Any thread may 
have a custom context switcher for when it gets switched in and a different switcher 
for when it gets switched out. In addition, a custom scheduling procedure may be 
defined that gets called every time thread rescheduling occurs. All of these features 
may he used by both types of threads. 

The Thread Manager also provides debugging support: a program or debugger can 
register callback routines with the Thread Manager so rhat it gets notified when a 
thread is created, deleted, or rescheduled. 

THE MAIN THREAD 

When an application launches with the Thread Manager installed, the Thread 
Manager automatically defines the application entry point as the main cooperative 
thread. The main cooperative thread is commonly referred to as the gpplkatim thread 
or main thread f . There are several guidelines you should follow regarding the main 
thread. These aren’t hard and fast rules, bat just guidelines to keep you from having 
debugging nightmares. Remember that cooperative threads must make explicit use of 
the Thread Manager API to give time (yield) to other cooperative threads. 
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First, the Thread Manager assumes the main thread is the thread that handles the 
event mechanism (WaitNextEvent, GetNextEvenr, Modal Dialog, and so on). Events 
that can cause your application to quit should be handled by the main thread: the 
application was entered through the main thread and should exit through it as well. 
The Thread Manager schedules the main thread whenever a generic yield call is 
made and an OS event (such as a key press or mouse click) is pending. This is done to 
speed up user-event handling; otherwise, it could take a long time before the main 
thread got time to run, because of the round-robin scheduling mechanism used for 
cooperative threads. In general, all event handling should he done from the main 
thread to prevent event-handling confusion. For example, i! the main thread calls 
WaitNextEvent while another thread is calling GetNextEvenr while yet another 
thread is calling ModalDialog, and they’re all yielding to each other, sorting out 
which event belongs to which thread becomes a nightmare. Just let the main thread 
handle all events. Your application will run faster and work better in the long run. 

The second guideline is to avoid putting the main thread in a stopped state. Doing so 
is perfectly legal but can lead to some exciting debugging if your application makes 
incorrect assumptions about die state of the main thread. 

Last but not least, be sure you call MaxApplZone from the main thread to frilly 
extend your application heap before any other cooperative threads get a chance to 
allocate, or move, memory. This requirement is due to the limitation on cooperative 
threads extending the application heap — they can't. 

DISPOSING OF THREADS 

When threads finish executing their code, the Thread Manager calls DisposeThread. 
Preemptive threads are recycled to avoid moving memory. Recycling a thread causes 
the Thread Manager to clear oul the internal data structure, reset it, and place the 
thread in the proper thread pool. (There are two pools, one for cooperative and one 
lor preemptive threads.) Since recycling a thread doesn't move memory, preemptive 
threads can dispose of themselves and other threads safely. 

The Thread Manager handles disposing of threads automatically, so it's not necessary 
for the last line of your code to call DisposeThread unless you want to — for 
example, to recycle all terminating cooperative threads. DisposeThread takes three 
parameters: the thread ID of the thread to be disposed of, a return value to return to 
the creator of the thread, and a Boolean Hag that tells the Thread Manager whether 
or not to recycle the thread, A preemptive thread should only call DisposeThread 
with the recycle flag set to true. 

The Thread Manager API also defines a routine, SetThreadTerminator, that allows 
your application to install a callback routine to be called when a thread terminates — 
which is when it's disposed of; You could use SetThreadTerminator to do any cleanup 
needed by the application, but remember, you can't move memory during 
termination of a preemptive thread because you're still in the preemptive state. 
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When your application terminates, threads are terminated as follows: 

* Stopped and ready threads are terminated first but in no special 
order* 

• The running thread, which should be the main thread, is always 
terminated last* 

CODE ORGANIZATION 

To use the Thread Manager most effectively, break your applications into discrete 
functional pieces, similar to the code organization used for object-oriented 
applications. Keep the code for event handling, window management, calculation, 
and drawing separate. In general, design your code such that the discrete parts may 
run independently of each other, but in an organized and coherent way. Object¬ 
or iented code, in general, is designed this way and is much easier to think about in a 
concurrent manner. The following sections discuss techniques that you can use to 
write more effective thread code. The examples illustrate what we learned from lots 
of trial and error during the development of the Thread Manager, which should 
reduce the development time for your threaded applications. 

THREAD INPUT AND OUTPUT PARAMETERS 

When creating a thread, you can pass in both a thread input parameter and a return 
value storage location* The Thread Manager defines the input parameter as a void* 
and the return parameter as a void**. Don’t let the messy C-language semantics get 
you down; it's actually quite easy to understand. 

The Thread Manager assumes the input parameter is the size of a void* (a 32-bit long 
word for Today’s 680x0 applications) and is passed to your thread as such. Any value 
may be passed as die input parameter, as long as ids the size oi a void*. Passing nil as 
this parameter will simply pass nil -— not nothing — as your threads input parameter* 

The return parameter is a litrie messier* In asking tor a void**, the Thread xManager is 
asking for the memory location to store die void* returned by the thread. If nil is 
passed as the return value storage location, the Thread Manager assumes there's no 
return value and won’t bother to set it on thread completion. Your thread may return 
any value as long as ids die size of a void*. The address passed in as the return value 
storage location can be simply the address of a long-word local variable (a long word 
is the size of a void*) or can he as complicated as the address of a global variable 
record pointer* The idea is that the Thread Manager wants, as the return value 
storage location, the address in which to store a value the size of a void** The Thread 
Manager stores the returned value at thread termination time by using either a 
return (x) statement or a DisposeThread call. 

Don’t pass the address of a short-word local variable as the return value storage 
location, because a short w T ord is shorter than a void** When the thread terminates, 
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the Thread Manager will slam all 32 hits of the return value (the size of a void*) into 
the short word, destroying the high word of your next defined variable. You must also 
make sure the storage location used for the return parameter is valid at the time the 
thread terminates. For example, if you use a local variable as the storage location, you 
need to be sure the new thread will terminate before you return from the routine that 
created it (that is, before the local variable goes out of scope). 

The following code samples show two methods of sending in thread parameters and 
returning thread results. First let’s define some constants and the record structure 
used in the example: 

idefine kUoCreationOptions 0 /* Just use the standard default */ 

/* creation options, */ 

idefine kDefaultThreadStackSize 0 /* Zero tells the Thread Manager */ 

/* to use the default value, */ 


struct ExampleRecord { 
long someLongValue; 

short someShortValue; 

}? 

typedef struct ExampleRecord ExampleRecord; 
typedef ExampleRecord *ExampleRecordPtr? 

The kNoCreacionOptions #define specifies the default creation options. These 
options create a thread using newly allocated memory from the Memory Manager 
with the thread in the “ready” state; the thread will have its FPU context switched 
dunng a reschedu 1 e. The kDefaultThreadStacksize #defi ne tells die Thread xManager 
to use the default stack size for the thread. 


Now let’s look at the routine prototypes and diread parameters: 
pascal long ExampleOne (long); 

pascal ExampleRecordFtr ExampleTwo (ExampleRecordPtr inputRecordParam); 


void ParametersExample 

{ 

ThreadID 

QSErr 

long 

short 

Boolean 

long 

E xamp1eRecordPfr 
ExampleRecord 


(void) 

tempThreadlD; 

err; 

myLong; 

myShort; 

notDone = true; 

longResult = -1; 

recordOutResult = nil? 

recordlnParam; 


CONCURRENT PROGRAMING WITH THE THREAD MANAGER March 1994 






In the call to create the first thread, the numeric value 42 is passed in as the input 
parameter The return value storage location is the address of a long-word local 
variable. Remember, you can't return from this function until the new r thread 
terminates — the local variable return value storage must stay valid. 

err = NewThread(kCooperativeThread, (ThreadEntryProcPtr)(ExampleOne), 
(void*)42 , kDefaultThreadStackSize, kNoCreationOptions, 

(void* *)&longRe sult, &tempThreadID); 
if (err) 

DebugStr("\p Could not make coop thread I"); 

To create the second thread, the address of a locally allocated data structure is passed 
as the input parameter. The return value storage location is the address of a local 
variable used to hold a pointer to die type of data structure to be used for storing the 
return value. Again, you can’t return from this function until the new thread 
terminates. 

recordlnParam.someLongValue = OxDEADBEEF ; 
recordlnParam.someShortValue = OxBADD; 

err = NewThread(kCooperativeThread, (ThreadEntryProcPtr)(ExampleTwo), 
(void*)&reeordInParam r kDefaultThreadStackSize, kNoCreationOptions, 

(void * *)& recordOutResult, & tempThreadID); 
if (err) 

DebugStr( 11 Yp Could not make coop thread 2"); 

Now that the two threads are created and ready to run, rhe code sirs in a loop 
handling user events, yielding, and waiting for the threads to complete their work. 

while (notDone) 

{ 

YieldToAnyThread (}; /* Other threads run. */ 

This code looks to see whether the first thread has completed and, if it has, goes off 
and does what computers do best — compute on the data. 

if (longResult J= -1) 

{ 

GoHandleThreadReturnResult(longResult); 
longResult = -1; /* Reset the value. */ 

> 

Now the code checks to see whether the second thread has completed. It there’s a 
non-nil value in recordOutResult, the data is available. It’s then sucked out of the 
record into the local variables and sent on ins way to be used by the application. 
Notice that the record structure that was allocated by the second thread is disposed of. 






if (recordOutResuit !- nil) 

{ 

myLong = recordOutResult->soTTieLongValue; 
myShort = recQrdOutResult->someShortValue; 

DoStuffWithParams(myLong r myShort); 

DisposePtr((Ptr)recordOutResuit); /* Toss it* */ 

recordOutResuit = nil; /* Neutralize it. */ 

> 

/* Handle user events until we quit. */ 

GoHandleEvents(SnotDone); /* WaitNextEvent event handling. */ 

} 

return; /* Out of here. */ 

> 

In the code for the first thread, both the input and output parameters are longs, and 
the thread simply returns the value sent to it. The important point here is that both 
the input and output parameters are the size of a void*- 

pascal long ExampleOne (long inputParam) 

{ 

return (inputParam); /* Must be the size of a void*. */ 

} 

The code for the second thread is a little more complex. Here, we allocate the storage 
needed for the record that will be passed back to die creator. It’s the creator's duty to 
dispose of the data after using it. The record elements from the input parameter are 
used as the source material for the elements within the record being returned to the 
creator Again, both the input and output parameters are the size of a void*. 

pascal ExampleRecordPtr ExampleTwo (ExampleRecordPtr inputRecordParam) 

{ 

ExampleRecordPtr myRecordPtr; 

myRecordPtr = NewPtr{sizeof(ExampleRecord)); 
myRecordPtr->someLongValue = inputRecordParam->someLongValue; 
myRecordPtr->someShortValue = inputRecordParam->someShortValue ; 

return (myRecordPtr); /* Must be the size of a void*. */ 

} 

PARANOID PREEMPTIVE PROGRAMMING 

If a preemptive thread can preempt, it will preempt. This can cause problems, 
especially when you create new preemptive threads. When you create a preemptive 
thread in the ready state, it's free to run whenever preemption occurs. This could 
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mean that your preemptive thread fires off before data it might need is available or set 
up. There are two simple solutions, illustrated in the examples that follow: create the 
preemptive thread in the stopped state and wake it up when you're ready to let it run, 
as shown in the first example, or wrap all creation of “ready” preemptive direads 
widiin critical sections, as shown in the second example. Remember that preemptive 
threads can’t preempt code that’s wrapped within critical sections. 

Here’s the example of creating a preemptive thread in the stopped state: 

pascal void* aThread (void* parameter) 

{ 

/* Preemptive threads don't need to call Yield, */ 
while (true)? /* Infinite loop* */ 

> 

void somefunction (void) 

{ 

ThreadID theThreadID; 

QSErr theError; 

theError - NewThread(kPreemptiveThread, 
aThread, 
nil, 

kDefaultThreadStackSize, 
kNewSuspend, 
nil, 

&theThreadID); 
if (theError 1= noErr) 

DebugStr("\pFailed to create thread"); 

/* Uow wake the thread up. */ 
theError = SetThreadState(theThreadID, 

kReadyThreadState, 
kNoThreadID); 

if (theError) noErr 

DebugStr ( T, \pFai led to set the preemptive thread to the ready 
state,"); 

1 

The parameter kNewSuspend in the NewT bread call tells the Thread Manager to 
create the thread in the stopped state. The SetThreadState call is used to wake up the 
thread. The last parameter to SetThreadState suggests to the Thread Manager which 
thread to execute after this call; this parameter is used only if the state of the 
currently executing thread is being changed. At this point, the preemptive thread is 
allowed to begin execution whenever it can. 


/* Type of thread */ 

/* Thread entry point */ 
/* Input parameter */ 

/* Stack size */ 

/* Creation options */ 

/* Return result */ 

/* New thread ID */ 


/* Thread to set */ 

/* New state */ 

/* Suggested thread */ 





Here's how to create a preemptive thread within a critical section: 

pascal void* aThread (void *parameter) 

{ 

/* Preemptive threads don’t need to call Yield. */ 
while (true}? /* Infinite loop. */ 

> 

void somefunction (void) 

{ 

ThreadID theThreadID; 

ThreadBeginCriticalf); /* Disable preemption. */ 

theError = MewThread(kPreemptiveThread r aThread, nil, 

kDefauifThreadStackSize, kWoCreationOptions, nil, StheThreadlD); 
if (theError 1= noErr) 

DebugStr("XpFailed to create a preemptive thread’ 1 ); 
ThreadEndCritical{); /* Enable preemption. */ 

} 

AVOIDING QUICKDRAW FROM PREEMPTIVE THREADS 

As mentioned earlier, you can’t call QuickDraw from preemptive threads because 
QuickDraw isn’t interrupt safe and you have to obey the rules of executing during 
interrupt time w hen you use preemptive threads. There’s no way around this, but you 
am draw from preemptive threads with some extra work. 

First you need to write your own primitives for drawing. This can be as simple as 
blasting pixels with *(pixeIPtr) = OxFFFF or as complex as writing your own 
primitives for all drawing. Next you create a GWorld for your preemptive thread to 
draw into. The idea is to modify this GWorld and then later use CopyBits from a 
cooperative thread to blast it to the screen. There are just a couple of things to 
remember before you start using the preemptive thread’s GWorld: make sure yon 
lock down the PixMap handle within the GWorld using 11 Lock and make sure you 
call LockPkels for that GWorld. This guarantees there won't be any memory moving 
while you’re drawing into the GWorld with preemptive threads. 

APPLICATION/THREAD MANAGER SCHEDULING 

This section provides code examples for creating your own scheduler and context- 
switching routines. Figure 2 shows how your custom scheduler and custom context¬ 
switching routines are executed in conjunction with the Thread Manager’s own 
scheduling routines. 
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Figure 2 

Thread Scheduling With Custom Scheduler and Context Switcher 
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CUSTOM SCHEDULERS 

Occasionally, the YieldToThreadfThreadlD) call is insufficient as a thread-scheduling 
mechanism. Assigning a custom scheduler function gives localized control over 
thread scheduling within your application. From this function you can inform the 
Thread Manager which thread you M ould like to schedule. Here’s the header 
information that deals with custom schedulers (it’s extracted from Threads.h): 

/* Information supplied to the custom scheduler */ 
struct SchedulerlnfoRec { 
unsigned long infoRecSize; 

ThreadiD CurrentThreadID; 

ThreadID SuggestedThreadID; 

ThreadiD InterruptedCoopThreadID; 

}? 

typedef struct SchedulerlnfoRec SchedulerInfoRec; 
typedef SchedulerlnfoRec *SchedulerInfoRecPtr ; 

typedef pascal ThreadiD (*ThreadSchedulerProcPtr)(SchedulerInfoRecPtr 
schedulerInfo); 

Note that the Thread Manager passes the custom scheduler the ID of the current 
thread (CurrentThreadID) and the ID of the thread that the Thread Manager is 
going to schedule (SuggestedThreadID). If a cooperative thread was preempted and 
has not yet resumed execution, the ID of that thread (InterruptedCoopThreadID) is 
passed to the custom scheduler; kNoThreadID is passed if there’s no cooperative 
thread waiting to resume from being preempted. With this information, all you have 
to do is tell the Thread Manager which thread to execute next by returning the 
thread ID of the thread you want to run. 

There’s one rule you must follow when returning a thread ID: if the value of 
InterruptedCoopThreadID is not equal to 0, return the InterruptedCoopThreadID 
value or the ID of any ready preemptive thread. This is because scheduling a different 
cooperative thread while another cooperative thread has been preempted would 
cause cooperative thread preemption and could result in a system misunderstanding 
(crash). If you don’t care which thread the Thread Manager schedules next, you can 
just return the constant kNoThreadID. If die value of CurrentThreadID is 
kNoThreadID, the Thread Manager schedules the first available ready thread by 
default; your custom scheduler may override this. 

During the execution of a custom scheduler, certain conditions exist: preemption is 
disabled to take care of any reentrancy problems and your AS world is not guaranteed 
to be valid. You’re probably thinking, “Geez, I have to worry about AS!” We show 
you a quick way to get around that in the example below, by using Gestalt to store 
AS. A few more tilings about custom schedulers: You can't yield from within a custom 
scheduler, nor can you cause scheduling to recur from this function. Also, only ready 
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and running threads are valid for rescheduling — and you can’t call SetThreadState 
from the custom scheduler. 

OK, enough background — here’s the custom scheduler example; 

#include "GestaltValue.h” /* Gestalt utility. */ 

pascal ThreadID myThreadScheduler (SehedulerlnfoRecPtr mySchedulerinfo) 

{ 

long currentAS, myA5; 

ThreadTaskRef currentTaskRef; 

/* The task ref is our Gestalt selector- */ 

GetThreadCurrentTaskRef(&currentTaskRef); 

/* Get applications A5. If we can’t, let Thread Manager do it all. */ 
if (Gestalt(currentTaskRef, &myA5) J = noErr) 
return kNoThreadID; 

/* Was a cooperative thread preempted? If so, let Thread Manager */ 

/* continue. */ 

if (mySchedulerInfo->InterruptedCoopThreadID i= kNoThreadID) 
return mySchedulerInfo->InterruptedCoopThreadID; 

/* Restore application’s A5- */ 
currentAS = SetAS(myA5); 

/* Now you can determine what you want to do. You have access to all */ 
/* your globals, so select a thread to run- */ 

/* Restore the A5 we entered with- */ 
myA5 = SetAS(currentAS); 


void initAll (void) 

{ 

long myAS ; 

ThreadTaskRef currentTaskRef; 

OSErr myError; 

/* Do standard initialization stuff here. */ 
myAS - SetCurrentAS(); 

/* Get a unique value to use as a gestalt selector- */ 
GetThreadCurrentTaskRef(tcurrentTaskRef); 
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/* Set up a Gestalt value to use. */ 

if {(myError - NewGestaltValue(currentTaskRef r myA5)) 1= noErr) 

{ 

/* Does it already exist? It better not! */ 
if (myError == gestaltDupSelectorErr) 

DebugStr{'■ ^Won’t replace Gestalt selector."); 

} 

> 

CUSTOM CONTEXT SWITCHERS 

Now we come to the next feature the Thread Manager supplies for dealing with 
scheduling: custom context switchers. You might ask, what is a thread context? The 
default context of a thread consists of the CPU registers, the FPU registers if an FPU 
is present, and a few internal globals. The saved data is as follows: 

* CPU registers: D0-D7; A0-A7; SR (including CCR) 

* FPU registers: FPCR, FPSR, FPIAR; FP0-FP7 

The thread context lives on the thread’s A7 stack, and the location of the thread 
context is saved at context switch time. Initially, the A5 register (which contains a 
pointer to the application’s AS world) and the thread MMU mode (24-hit or 32-bit) is 
set to be the same as the main thread. This allows all threads to share in the use of the 
application’s A5 world, which gives threads access to open files and resource chains, 
for example. To allow preemption of threads that change the MMU operating mode, 
the MMU mode is saved as part of the context of a thread. The FPU context is fully 
saved along with the current FPU frame. 

Custom context switchers don’t need to worry about saving the standard CPU 
context, as this is done by the Thread Manager. When writing a custom context 
switcher, keep in mind that preemption is disabled while it executes. Just as in custom 
schedulers, don’t make any calls that can cause scheduling. In addition, w hen the 
custom context switcher is being called, the thread context is in a transition state, so 
any calls to GetCurren (Thread won’t w ? ork, nor will any calls to which you pass 
kCurrentThreadID as a parameter. As with the custom scheduler, you’re not 
guaranteed to have AS set up for you; the example below shows how to get around 
that. 

You may have context switchers for when a thread is entered (switcher-inner) and 
when a thread is exited (switcher-outer). Which context switcher to use is determined 
by a parameter passed to the SetT h read Switcher routine. Here’s the header 
information on custom context switchers (extracted from Threads, h); 

typedef pascal void (*ThreadSwitchProcPtr}(ThreadID threadBeingSwitched, 
void *switchProcParam); 
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pascal OSErr SetThreadSwitcher (ThreadXD thread, ThreadSwitchProcPtr 
threadSwitcher, void *switchProcParami Boolean inOrOut); 

Besides die selector for whether the switcher is an inner or an outer, the application 
can supply a parameter to the switch function. This parameter may vary for every 
thread, allowing you to write only one custom context switcher. It isn’t necessary to 
have a switcher for both entry and exit, and all threads can share the same switcher. 
One last thing to remember about switchers is that a switcher-inner is called 
immediately before the thread begins execution at the entry point. 

Here’s an example of a custom context switcher: 

Idefine switcherlrmer true 
#define switcherOuter false 

struct myContextSwitchParamStruct 

{ 

long appsAS,' /* Save application’s A5. */ 

/* Anything else you my need for your custom context switch, */ 


} r 

typedef struct myContextSwitchParamStruct myContextSwitchParamStruct; 
struct myContextSwitchParamStruct gMyContextSwitchParam; 

pascal void* aThread {void ^parameter) 

{ 

/* Does something, */ 

YieldToAnyThread(); 


pascal void myThreadSwitchProc (ThreadlD theThreadBeingSwitched, 
void *theSwitchProcParam) 

{ 

long currentAS, myA5; /* A5 when our custom switcher was called. */ 

myA5 = ((myContextSwitchParamStruct *jtheSwitchProcParam)->appsA5; 

/* Restore application’s A5. */ 
currentAS = SetA5(myA5); 

/* Now you can determine what you want to do. You have access to all */ 
/* your globals, so do any context stuff. */ 

/* Restore the A5 we entered with. */ 
myA5 = SetA5(currentAt); 
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void initAll (void) 

{ 

ThreadID theThreadlD; 

OSErr theError; 

/* Do standard initialization stuff here* */ 

/* Set up AS in switch parameter. */ 
gMyContextSwitchFaram*appsA5 = SetCurrentAS (); 

/* Create a thread. */ 

theError = NewThread(kCooperativeThread, aThread, nil, 

kDefaultThreadStackSize, kNoCreationOptions, nil, stheThreadlD) ; 
if (theError J = noErr) 

DebugStr("\pFailed to create a cooperative thread"}? 
theError = SetThreadSwitcher(theThreadlD, myThreadswitchProc, 

(void*) &gMyContextSwitchParam, switchlnner) ; 
if (theError 1= noErr) 

DebugStr( rr \pFailed to set custom context switcher-inner"); 


> 

DIALOGS THAT YIELD 

Aren’t you tired of having your dialogs hang up your application while you wait lor 
the user to do something? With the Thread Manager you can alleviate this problem 
by making only one call, Yi e ldToAnyTbread. Basically, if your program is broken into 
multiple threads, you can put the dialog handler in one of those threads (usually the 
main thread is best) and have the dialog’s filter procedure call YieldToAnyThread. 
This gives any other threads that are waiting time to run. When the user makes a 
choice in the dialog, the main thread is scheduled automatically by the Thread 
Manager so that your application can handle that event immediately. While the user 
is getting a cup of coffee, your application can finish whatever other tasks are 
appropriate, without slowing the machine down. 

In the following example, YieldFilter is a filter procedure for a dialog that just calls 
YieldToAnyThread, to give other threads time while the dialog is in the front This 
allows threads “behind” the dialog to continue to process information, 

pascal boolean YieldFilter (DialogPtr theDialogPtr, EventRecord *fheEvent, 
short *theltemHit) 

{ 

/* Yield to whoever wants to run. */ 

YieldToAnyThread()? 

/* Call the 7*0 standard filter procedure defined in Dialogs.h. */ 
return (StdFilterProc(theDialogPtr, theEvent, theltemHit)); 

> 
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/* The DoOKDialog function just handles a simple OK dialog. */ 


void DoOKDialog (short dialogiD) 

{ 

DialogPtr theDialog ; 

short itemHit; 

GrafPtr savePort; 

OSErr theError; 

GetPort(&savePort ); 

if ((theDialog = GetNewDialog(dialogiD, HULL, (Ptr}-1)) != NULL) 

i 

SetPort(theDialog); 

ShowWindow(theDialog); 
do 
{ 

ModalDialog(YieIdFilter f &itemHit); 

} while (itemHit 1= okButton); 

DisposDialog(theDialog); 

} else 

DebugStr( "\pCould not find dialog' 1 ); 

SefPort(savePort); 

> 

THREAD-BLOCKING I/O 

In general, thread-blacking I/O occurs when code making an I/O call sleeps until the 
I/O call completes. The basic problem with doing thread-blocking I/O with the 
Thread Manager is that threads are application based, not systemwide Device 
Manager I/O based. This means that threads are really good at doing work at the 
application level but aren’t designed to auto-hlock on I/O — that’s your job. 
Fortunately, the Thread Manager provides all the tools needed to create your own 
thread-blocking I/O, 

I/O WITH COOPERATIVE THREADS 

Let’s suppose you use a thread to make an asynchronous I/O call. Then the thread 
goes to sleep, waiting for the completion routine to wake it up. The problem is the 
completion routine can (and will) fire off before the thread is able to be put to sleep 
— there’s a window of misfortune after the thread makes the asynchronous call and 
before h completes the sleep call. Having nothing to do, the completion call just 
returns. The thread then makes the sleep call and will sleep forever, waiting For a 
completion routine that already occurred. 
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A completion routine, or any other code running on the Macintosh, may ask for the 
state of a thread in an application by using GetThreadStateGivenlaskReh Given a 
task reference to a particular application and a thread ID, you can get the state of any 
thread. If that thread is sleeping, you can call S etThread ReadyGi ve n Task Re f, which 
will tell the Thread Manager to mark the thread as ready. The thread is not actually 
made ready, just marked ready. The next time a reschedule occurs in the application, 
the marked thread is made ready and is eligible to run. 

Note that you can’t just check to see if the thread isn’t in the running state because it 
could have been preempted (and probably was if possible) before it made the sleep 
call, when the completion routine fired. You must wait for the thread to be in die 
stopped state before making a call to S etThread Re a dyGivenTaskRef 

One solution is to have the completion routine use one of the interrupt-safe routines 
and ask the Thread Manager if die thread in question is sleeping yet and, if it is, ask 
the Thread Manager to wake it up. If it’s not sleeping yet, set up a timer task (or VBL 
or Deferred Tisk Manager task) to ask again later, and keep asking until the thread is 
sleeping; then wake it up. 

As you can imagine, die “poll until thread stopped” solution is messy and time 
consuming. A cleaner solution is to have a second thread whose only job in life is to 
wake up the first thread after it goes to sleep (after making the asynchronous I/O 
call). The following steps show how to do this for the two threads ThreadA and 
ThrcadB. 

From a cooperative thread — ThreadA: 

1. Create a cooperative thread, ThreadB, in the stopped state. 

2. Set die completion routine to wake up ThrcadB when it fires off. 

3. .Make die asynchronous I/O call from ThreadA. 

4. Put ThreadA to sleep, forcing a reschedule with the 
S etThread State calk 

5. After ThreadB wakes up ThreadA, ThreadA magically continues 
running right where it left off! This is what’s fun with concurrent 
programming. 

From the completion routine: 

1. Be safe and make the GefTh read State Give nTaskRef call on 
ThreadB. 

2. If ThreadB is not in a stopped state, give up. Things arc in a bad 
way ThreadB should be in the stopped state, since it was created 
that way. 
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3* Make a call to SetThreadReadyGivenTaskRef on Thread B to 
mark it ready. The Thread Manager will actually make it ready at 
the next reschedule time. 

4. That’s it; just return* 

While executing cade from the cooperative thread, ThreadB, you know' the following 
to be true: 

* ThreadB is cooperative* 

* You’re executing code in ThreadB* 

* ThreadA is cooperative. 

* Only one cooperative thread may run at a time* 

■ ThreadA didn’t yield to anybody and is therefore not in the ready 
state while ThreadB is running. 

* ThreadA put itself in the stopped state, which caused a reschedule. 

* Since cooperative ThreadB is running, ThreadA can’t be running. 

* Therefore, ThreadA is in the stopped state* 

From the above truths, all ThreadB needs to do is set the thread state of I bread A to 
ready. The following steps wake up ThreadA from ThreadB: 

1. Set the state of ThreadA to ready with the SetThreadState call. 

2. Return, 

The big concept is that only one cooperative thread can run at a time* Cooperative 
threads can’t preempt each other* The only way to get from one cooperative thread to 
another is by yielding — making a yield call or setting the state of the running 
cooperative thread to ready or stopped. If a cooperative thread, ThreadA, sets itself to 
stopped, another cooperative thread, ThreadB, knows that because it (ThreadB) is 
running, ThreadA must he stopped. I lowever, this scheme works only if there are 
other (at least one) cooperative or preemptive threads that can run while the wake-up 
thread and the thread making the I/O call are stopped. It’s highly recommended that 
you never stop the main thread; this will keep you safe for doing thread-blocking I/O 
w ith a thread making an I/O call and a wake-up thread. Keeping die main thread 
ready also keeps the Macintosh user interface active. 

To summarize the preceding steps: The cooperative thread doing the I/O creates a 
cooperative wake-up thread (in the stopped state), makes an asynchronous I/O call, 
and tells the Thread Manager to put itself in the stopped state. The completion 
routine fires off any time after the I/O call and makes a call to mark the wake-up 
thread as ready. Once the thread that made the I/O call goes to sleep, rescheduling 
occurs and, if the wake-up thread is ready, it’s made eligible for running* Normal 
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thread scheduling occurs until the wake-up thread is run. The only thing the wake-up 
thread needs to do is tell the Thread Manager to set the state of tire thread making 
the I/O call to ready and return. Rescheduling will occur and the thread that made 
the I/O cal! will continue on its merry way as if nothing had happened. This process 
is illustrated in Figure 3. 


Mai n Threa d 
I/O Thread 


Yield 


Yield---- 



Time 


Running/executing 
=► Stopped 


-—* — -► Ready to run 


State transition / reschedule 


Available to be made ready 
at next reschedule 


Figure 3 

Timeline State Flow Diagram for Threaded I/O 


I/O THREAD BLOCKING EXAMPLE 

Now let’s see how the preceding solution looks in code. We begin by setting up 
housekeeping and doing some administrative stuff. The extended parameter block 
structure is used to store the parameter block used by the file system as well as data 
used by the completion routine. The first element of the structure must be the file 
system parameter block, as this is the address passed into the file system call. The 
next two parameters are used by the completion routine to get the application task 
reference and thread ID of the thread to wake up. These values are stored here 
because completion routines can’t access the application globals when they’re called. 

To finish up the housekeeping, we define the routine prototypes and the inline 
routine GetPBPtr. Completion routines are passed the address of the parameter 
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block in register AO, so the GetPBPtr routine is needed to retrieve the parameter 
block. 

struct ExtendedParamBlk { 

/* PB must be first so that the file system can get the data. */ 

P ar amB1ockRec pb ; 

ThreadTaskRef theAppTask; 

ThreadID theThread; 

} * 

typedef struct ExtendedParamBlk ExtendedParamBlk; 
typedef ExtendedParamBlk *ExtendedParamBlkPtr; 

/* Routine prototypes. */ 

pascal void lOExampleTbread (void); 

pascal void WakeUpThread (ThreadID thread!oWake); 

void MyCompletionRoutine (void); 

/* Completion routines are called with register AO pointing to */ 

/* the parameter block. */ 

pascal ExtendedParamBlkPtr GetPBPtr(void) - (Qx2E88>; 

/* move.l aO, (sp) */ 

This is a routine in the main thread that creates a thread that makes an I/O call; 

void KickOffAnlOThread (void) 

{ 

ThreadID newCoopiD; 

OSErr theError; 

theError = NewThread(kCooperativeThread, 

{ThreadEntryProcPtr)IOExampleThread, nil, kDefaultThreadStackSize r 
kNoCreationOptions, nil, snewCooplD); 
if (theError) 

DebugStr{"\p Could not make cooperative I/O thread"); 

/* Return and let the I/O thread do its thing! */ 

} 

Below is the code for the thread that makes the I/O call — IOExampleThread, It 
makes an asynchronous I/O call with a completion routine that will wake up the 
wake-up thread, which then w akes up IOExampleThread. 

pascal void IOExampleThread (void) 

{ 

ThreadID wakeupThreadID, meThreadID; 

ThreadTaskRef theAppRef; 
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Extended?aramBlk myAsyncPB; 

OSErr theError, thelOResult; 

/* Get the ID of lOExampleThread. */ 
theError = GetCurrentThreadID( SrineThreadlD); 
if (theError != noErr) 

DebugStr("\pFailed to get the current thread ID"); 

/* Get the application's task reference. */ 
theError ® GetThreadCurrentTaskRef(StheAppRef); 
if (theError I- noErr) 

DebugStr( n \Could not get our task ref"); 

/* Create a wake-up thread, */ 
theError = NewThread(kCooperativeThread, 

(ThreadEntryProcPtr)WakeUpThread, (void*)meThreadiD, 
kDefaultThreadStackSize, kNewSuspend, nil, &wakeupThreadID ); 
if (theError 1= noErr) 

DebugStr("\pFailed to create a cooperative thread"); 

I lore's where you prepare for the I/O call — a simple asynchronous flush volume 
command. Notice how we set the address of the completion routine. We also set up 
the extended data needed by the completion routine — the thread ID of the wake-up 
thread and the application’s task reference. 

myAsyncPB.pb.ioParam.ioCompletion = (ProcPtr)MyCompletionRoutine; 
myAsyncPB.pb.ioParam.ioResult “0? /* Initialize the result, */ 

myAsyncPB.pb.ioParam,ioNamePtr = nil; /* No name used here. */ 
myAsyncPB.pb.ioParam.ioVRefNum = -1; /* The boot drive. */ 

myAsyncPB.theThread = wakeupThreadID; 
myAsyncPB.theAppTask = theAppRef; 

lOExampleThread makes the I/O call and then calls SetThreadState to put itself to 
sleep. The first two parameters to SetThread State indicate the thread to set, which is 
lOExampleThread, and the state to set it to — stopped. The kNoThreadID 
parameter indicates that any ready diread can run next. 

PBFlushVol {(ParmBlkPtr) SrmyAsyncPB, async); 

theError = SetThreadState(kCurrentThreadID, kStoppedThreadState, 
kNoThreadID); 
if (theError noErr) 

Debugstr ("\pFailed to put ourselves to sleep”); 

At this point, lOExampleThread is sleeping, but other threads are running (including 
the main thread, because it’s not nice to put it in the stopped state). Meanwhile, 
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thread scheduling is taking place, so when the completion routine executes and tells 
the scheduler to place the wake-up thread in the ready queue, the wake-up thread can 
get scheduled to execute. (Make sure the main thread doesn't quit the application 
with the asynchronous I/O pending. You could run into problems when the 
completion routine tries to run but no longer exists because the application is gone.) 

Next the completion routine fires off and tells the Thread Manager to ready the 
wake-up thread. The wake-up thread eventually runs and tells the Thread Manager 
to ready the I/O thread. Then the I/O thread awakes and continues running as if 
nothing happened, continuing with the rest of the code. 

thelOResult = myAsyncPB.pb.ioParam.ioResult; 


> 


void MyCompletionRoutine (void) 


ExtendedParamBlkPtr 

ThreadTaskRef 

ThreadID 

ThreadState 

GSErr 


myAsyncPBPtr ; 

theAppTaskRef; 

theThreadID; 

theThreadState; 

theError; 


/* Get the parameter block. */ 
myAsyncPBPtr = GetPBPtr(); 

/* Get the data. */ 

theAppTaskRef = myAsyncPBPtr->theAppTask? 
theThreadID = myAsyncPBPtr->theThread; 

/+ See if the thread is stopped yet - just to be sure. */ 
theError - GetThreadStateGivenTaskRef(theAppTaskRef, theThreadID, 
GtheThreadState); 

/* If we can get the thread state, go for it! */ 
if (theError “ noErr) 

/* If it's awake, we have problems. */ 
if (theThreadState != kStoppedThreadState) 

DebugStr{"\pWake-up thread is in the wrong state! 11 ); 

/* Should be sleeping, mark it for wake upl */ 
else 

SetThreadReadyGivenTaskRef{theAppTaskRef, theThreadID); 

} 





The wake-up thread eventually begins execution and has only one job — to wake up 
the thread that made the I/O call. 

pascal void WakeUpThread (ThreadXD threadToWake) 

{ 

OSErr theError; 

/* Wake up the specified thread. */ 

theError = SetThreadState(threadToWake, kReadyThreadState, 
kNoThreadID); 

if (theError 1 = noErr) 

DebugStr{"XpFailed to wake our thread"); 

/* We’ve done our deed, so just return quietly and let it run* */ 

> 

I/O WITH PREEMPTIVE THREADS 

Things get a little tricky when the thread making the I/O call is preemptive — not to 
mention that you may not be allowed to make certain asynchronous I/O calls from 
preemptive threads (you know, the interrupt routine rules and all that). To solve the 
problem, all you do is force your preemptive thread to look like a cooperative thread. 
Before you make the asynchronous I/O call, you need to begin a critical section 
with the ThreadBeginCritical routine* Also, since you can’t create threads from 
preemptive threads (again, the interrupt routine rules), you need to get the wake-up 
thread from the thread pool you created earlier (you did create one, didn’t you?). 
After the I/O call, call SetThreadStateEndCritical rather than SetThreadState; this 
puts the tli re ad in the stopped state, ends the critical section to allow preemptive 
scheduling, and forces a reschedule all at the same time. Then, when the wake-up 
thread gets run, it knows that the thread that made the I/O call must be sleeping* 

FINAL THOUGHTS 

Here arc some final thoughts before you dive in and start programming with the 
T h r ead M a n age r: 

* Remember to always preload the code segments that will he used 
by preemptive threads. Since you’re not allowed to move memory 
during preemptive thread time, loading a code segment would 
definitely cause a problem* 

* Make sure you call MaxApplZone during the application’s 
initialization, especially before you start creating threads. The 
application’s heap won’t grow correctly from other cooperative 
threads, so you must fully grow your heap before any other thread 
allocates memory* 
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* When dealing with cooperative and preemptive threads in the 
same application, make sure you maintain data coherency between 
your threads. It’s very possible that a preemptive thread could 
change shared data out from underneath a cooperative thread 
that’s using it, A simple way to maintain data coherency is to use 
critical sections, 

* Be careful calling WaitNextEvent with a large sleep value when 
there are threads that need time. Threads get time to run only 
when your application gets time. Putting the application to sleep 
with WaitNextEvent means that your threads sleep, too. 

* Be very careful when quitting an application with suspended 
threads that will be awakened by an interrupt service routine. This 
can be a problem in some cases. The Thread Manager provides a 
thread termination procedure that's called when a thread is about 
to be disposed of— such as when the application quits — to 
handle any cleanup needed before final application termination. 

We urge you to use the Thread Manager because it will be integrated directly into 
the system software, and it will be upwardly compatible with the new RISC and OS 
directions Apple is taking. If you start taking advantage of the Thread Manager now, 
you’ll only be more ahead in the future. 
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VIEW FROM 
THE LEDGE 


TAO JONES 


Be tort: we get rolling here, I have a confession to make 
to those of you who have read this column in the last 
two issues. 1 feel I owe it to you for being so faithful. 
Due to lead times, publishing deadlines, and attempts 
to appear organized, develop authors actually write their 
MacNuggets of wisdom months before you read them. 
You’ve already had a chance to be in a New Year’s Day 
fight with your significant other, yet I’m writing this 
before Hallowe’en. 

I low do 1 put this? IVe been lying to you. The 
questions in my earlier columns were fakes. I made 
them up for my own self-aggrandizement. Which is 
bad enough, but I also gave myself the heartwarmingly 
collectible gift that’s supposed to be given to the 
dedicated readers who write in. Like Richard Nixon in 
the seventies, I guess the only defense I have is: 1 
misspoke myself. 

But that’s the past, and now my head reels because IVe 
received four letters. (Well, actually 1 received three and 
develop 1 ', s editor got a piece of hate mail.) Now 1 blow 
what it’s like to be 1/150,000th of “Dear Abby.” 


Dear 7do, 

Help! We have a power-hungry team member who is 
making the rest of the team thoroughly miserable! What am 
we do? Mutiny has crossed our collective minds, but after 


reading Mutiny on the Bounty none of mfancies suffering 
the fate of Mr Christian. 

Desperate 


Dear Desperate, 

In general you’ll find that the world is in turmoil for no 
reason other than intolerance. If people simply were 
more tolerant of each other’s beliefs, values, customs, 
and driving skills, the world would be a much more 
hospitable place. Typically you should try to live in as 
much harmony as possible with your office workers in 
an effort to spread peace and happiness in the world. 
This, however, is not one of those times. 

You may he surprised to learn that the answer to your 
problem was at your fingertips; you just failed to dig far 
enough for it. All you needed to do was ask yourself a 
simple question: What was the fate of Fletcher 
Christian? 

Historians have actually tried to cover up the real 
reason there was mutiny: it had nothing to do with ill- 
tempered leadership. Rather, Mr. Christian couldn’t 
stand being in an island-sized sauna with the obese 
Captain Bligh any longer. To remedy the situation, Mr. 
Christian decided to send Bligh on a crash diet the old- 
fashioned way: by making him row across 3500 miles of 
open ocean. 

Shortly after Bligh left, Air. Christian got out his 
Apple T computer with cassette tape backup (remember, 
this was a long ti me ago) and discovered that, by Jove, 
Bligh might actually make it. The last thing Mr, 
Christian wanted was to witness a size-6 Bligh parade 
his new physique around the island. So, he gathered up 
a bunch of Tahitian babes, sailed over to Pitcairn 
Island, burned the Bounty, and lived the rest of his life 
sipping coconut juice in a tropical paradise. The only 
penalty was that he would never be able to go back to a 
country where they serve a dish called U S potted Dick” 
for dessert, 'lb say it was a fair trade is a gross 
understatement. 


TAO JONES was slurmed when he discovered that the actual Too Index: Roughly 50% of the lawyers in the world graduated 
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Taking a cue from Mr. Christian, I’d say the following 
actions are in order; First, get a detailed plan of your 
huilding(s) and find the spot that’s the furthest from 
where the mutiny will actually take place; this will be 
your equivalent of Pitcairn Island, Due to twentieth- 
century building layout, it’s very possible that you may 
have to choose someplace like a boiler room. This gives 
you the tropical climate by default, but I’d add some 
sand and a few posters just to spice the place up a hit. 
Don't forget to stock enough coconut milk to last until 
your management turns its attention to some other 
crisis. Two weeks worth is probably more than enough. 

Then, mutiny to your hearts content. Start by issuing a 
new org chart, and when your troublemaker comes to 
protest, just do whatever seems to be most natural. Be 
as loud and obnoxious as possible, and don’t forger to 
throw in lines like “You call yourself a ship’s Captain?” 
and “From now on you get your own breadfruit trees!” 
Burning things to the ground is optional, 1 wouldn’t 
recommend it if your paycheck is important to you. 

There’s a good chance you’ll be set fur life. Just be sure 
you don’t get so carried away that you start sending 
postcards to your colleagues from your island retreat. 
Nothing gives away a hiding spot like a postmark. 

Dear Tito , 

Every time I get up quickly l become dizzy . Everyone thinks 
I have a drinking problem. What am I do ? 

Spinning in Sacramento 
Dear Spinning, 

You’re in a situation that has very serious physical and 
sociological implications and needs immediate 
attention. First and foremost, you should get yourself 
to a doctor. You may have something as complicated 
and life threatening as transient ischemic attack, or you 
may just be a ditz. Only a licensed physician will he 
able to tell for sure. By no means should you rely on 
self-diagnosis from watching reruns of “Marcus We I by, 


M.D.” Remember, the guy who played Dr. Kiley tried 
that and he ended up in The AmityviUe Horror, 

Whatever you do, if you go to a university to get 
checked, be certain the person you’re talking to is a 
Medical Doctor. You can’t swing a dead cat in that 
environment without hitting someone who is all too 
willing to be called “Doctor” yet thinks that “throat 
culture” has something to do with opera. These people 
have the title “Doctor of Philosophy” and their 
specialty is to heal problems with philosophical ideals. 

If you believe your dizziness is caused by an inability to 
understand dialectic materialism, this type of doctor is 
perfect; otherwise, steer clear. 

Unfortunately, getting fixed physically w r on’t heal the 
seeping sociological wound that has opened by 
everyone thinking you’re intoxicated. To tackle this 
part, first you should decide whether you deserve any 
time off from work. If you think you do, tell your boss 
you believe you have a substance abuse problem, and 
ask to have at least a month off to get yourself treated. 
If you happen to acquire a tan while you’re gone, say 
that you had to have minor UV therapy for jaundice. 

If you don’t want the time off, nr you want to squelch 
those rumors once and for all, simply stand up in your 
next company meeting and say something like, “I know 
many of you think 1 have a thinking problem due to my 
dizzy spells. This simply is not true. I just have a very 
strange habit of having my head reel whenever I get 
around a corporate back-stabbing weasel.” 


RECOMMENDED READING AND 
LISTENING 

* The Red Couch by Clarke, Moon, and Wackerbarth, 
Surprisingly, it's lots of pictures of o red couch. 

* War and Peace by Leo Tolstoy Good book. Great 
monitor stand. 

* Godzilla , on Star Child records. The original 
soundtrack; makes all other music sound great. 
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Have you seen this polar bear cub?" 


Tao needs questions \o keep from hoarding the freebies he is 
supposed Jo be sending out to you. the devoted reader. Send your 
queries regarding all aspects of office survival, or just that funny 
little thing we call "life," to AppleLink DEVELOP, ond there's a 
possibility that youll end up even cooler than you are now,’ 
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THE ZEN OF 


WINDOW 

ZOOMING 



DEAN YU 


Window zooming is a feature of the Macintosh user interface that's 
rarely implemented correctly. Because a lot of calculation and pixel- 
tweaking is required to achieve the “pet feet" window zoom, few 
applications go through the effort to properly zoom their document 
windows. This article discusses proper zooming etiquette and provides a 
routine that deals with all the details of zooming windows. 


About once a year, I gn on a tirade about how few programs zoom their windows 
properly. Most programs zoom to the full size of the main screen; other applications 
make the window only as big as they need to hut still move it to die main screen, 
even if the window is on another screen. The System 7 Finder comes close to making 
me happy, but every once in a while it zips a window to the main screen for reasons 
known only to the Finder engineers. 

As I was writing some application code recently, I took the opportunity to make it 
zoom windows the way 1 wish all other programs would zoom windows. The 
resulting code (which is on this issue’s CD) is the basis tor this article. The zooming 
behavior that this code implements reflects all the documentation Apple has ever 
published about window zooming, from the old Human Interface notes to the 
Window Manager chapter in Inside Macintosh: Macintosh Toolbox Essentials. 

THE ETIQUETTE OF ZOOMING 

First let’s look at the subtle effects of a user’s actions on how a window should be 
zoomed. After some basic definitions, well go over a few rules that govern zooming 
behavior. If you couldn’t care less about these preliminaries, you can skip to the 
section “The Zooming Code” (however, if you do this, you’ll hurt the author’s 
feelings, since be spent a perfect Saturday afternoon indoors to write this article), 

THE STATES OF A WINDOW 

A window is zoomed between two states, the user state and the standard state. The user 
state is any size and position in which the user can place the window on the desktop. 


DEAN YU recent!/ went on o cross-country rood 
trip in his new tor. In retrospect, he decided that 
the time off wasn't worth the emotional trauma of 
being pelted by marble-sized hail in Cheyenne, 
Wyoming, being salt-blasted in the Utah salt Flats, 
being nearly blown off the road as an 1 8-wheeler 
passed him at 95 miles an hour in the dead of 
night, and having his windshield chipped by 
gravel falling off a dump truck. Dean didn't even 


get the satisfaction of finding out exactly how fast 
he can drive without getting pulled over for 
speeding in Nebraska. Sympathy notes and 
donations for getting his car repaired can be sent 
to Dean in care of develop. * 
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The Window Manager updates the user state when it calls a WDEF to recalculate a 
window’s regions. 

The standard state of a window is defined to he the size that can best display the data 
contained in the window. For example, in word processing applications the standard 
state of a document window would most likely he the size of a printed page. For some 
types of windows the standard state depends on the window’s contents and so is 
determined dynamically by the application when the user zooms the window. In the 
Finder, for instance, die standard state of a window in an icon view would be the 
smallest size that can display all die icons in that window. The position of a window 
in its standard state varies depending on the position of the user state when the 
window' was zoomed and on other factors, as explained later. 

Figure 1 shows the user state and standard state of a Finder window displayed in the 
“small icon” view. 




Standard state 


Figure 1 

The User and Standard States of a Window 


RULES OF THE ROAD 

In addition, there are a few rules that govern how a window' should be zoomed in 
different situations. These rules can be divided into two categories: rules on size and 
rules on position. 

Rules on size* Although the standard state of a window is defined to be the best size 
for displaying the window’s contents, this state is actually constrained by the size of 
the screen to which the window is being zoomed. If the ideal size for die standard 
state is larger than the destination screen, the window should be pinned to the size of 
the screen, minus some slop pixels. For example, Figure 2 shows the height of the 
standard state being pinned on the main screen, (Note that space was also left for the 
menu bar,) 
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A lot of people think the Window Manager 
has some magic value slashed away in a dark 
corner that tells it whether a window is in its user 
state or its standard state. In reality, it's not that 
sophisticated. It's actually ihe WDEF that does all 
the work, since it's the thing that really needs to 
know which state a window is in. To make this 
decision, the standard document WDEF takes o 
window's portRect, converts it to global 


coordinates, and then compares it with the user 
and standard state rectangles to determine which 
state the window is in.* 
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If a window is being zoomed 
to tine main screen and the 
ideal size for Ihe standard 
slate wools lake up ihe entire 
width of the screen, a strip of 
space should be leu on ihe 
righl side of the screen to let 
the first column of the Finder 
icons show through 


Rules on positon 

The Basic guideline for position¬ 
ing b window during a zoom 
is that the window should move 
as little as possible, lo avoid 
dl&tractinp Ihe user 
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Ideal size 



Pinned standard state 


Figure 2 

Pinning to the Screen Size 


If a window is being zoomed to the main screen and the ideal size for the standard 
state would take up the entire width of the screen, a strip of space should be left on 
the right side of the screen to let the first column of Finder icons show through. 

Rules on position. The basic guideline for positioning a window during a zoom is 
that the window should move as little as possible, to avoid distracting the user. 

A window in its standard state should he positioned so that it's entirely on one screen. 
If a window straddles more than one screen in the user state and is subsequently 
zoomed to the standard state, it should be zoomed to the screen that contains the 
largest portion of the window’s content region. (See Figure 3,) 

When a window is zoomed from the user state to the standard state, it should be 
anchored at its current top left corner if possible. If the standard state size will fit on 
the screen without moving the window, the window can simply be resized. If the 
standard state of the window cannot fit with the top left corner anchored, the window 
should be “nudged” so that the parts that were off the screen fall just on screen. (See 
Figure 4.) 

THE ZOOMING CODE 

This section goes through the window zooming code chunk by chunk, discussing the 
logic behind each step. 

ZoomTheWindow is the entry point to the window zooming code. It determines the 
best screen to zoom the window to, and nudges the window into position in case part 
of it falls off the edge of the screen. Applications should call this routine instead of 
calling rhe Toolbox routine Zoom Window directly. 
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Standard state 


Figure 3 

Zooming to the Best Screen 
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Figure 4 

Nudge Zooming 


ZoomTheWindow has die following prototype: 

void ZoomTheWindow(WindowPeek theWindow, short zoomState, 

CalcIdealDocumentSizeProcPtr calcRoutine); 

The first two parameters, theWindow and zoomState, are identical to the first two 
parameters of Zoom Window. The last parameter, calcRoutine, is an application- 
supplied callback routine that calculates the ideal size for the window without taking 
the user's screen configuration into consideration. The prototype of the 
CalcIdealDocumentSizeProcPtr function type is as follows: 

typedef void (CalcIdealDocumentSizeProcPtr) (WindowPtr theWindow, 

Rect *idealContentSize); 

Given the window to be zoomed, the callback routine returns (in local coordinates) 
the ideal rectangle for the window in the idealContentSize parameter. The window 
will he the current graphics port when the callback routine is invoked. 

ZoomThe W1 ndow calls two utility routines, Ca leu I ateWmdowAreaOn Screen and 
CalculateOffeetAmount, CalculateWindowArea On Screen calculates the area of a 
window on a screen. The screen that contains the largest portion of the window- is the 
screen that the window will be zoomed to. If ZoomThe Window determines that 
anchoring the w indow at its current top left corner will result in part of the window 
lying off the screen, it calls CalculateGffeetAmount to find out how many pixels the 
window needs to be nudged so that it's entirely on the screen. These utility routines 
are described in detail following the discussion of ZoomTheWindow below. 
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THE ZOOMDATA STRUCTURE 

The ZoomData structure is used by ZoomTheWindow to hold information about 
the screen the window should be zoomed to. ZoomThe Window uses DeviceLoop to 
find the screen containing the largest portion of the window* The DeviceLoop 
drawing procedure updates the ZoomData structure as DeviceLoop calls it for each 
active screen device* 

struct ZoomData { 

GDHandle screenWithLarge stPartOfWindow; 

unsigned long largestArea; 

Rect windowBounds; 

>; 

typedef struct ZoomData ZoomData, *ZoomDataPtr; 

The screen With Larges tPartOfWindow field is a handle to the screen device that the 
window should be zoomed to* The larges tArea field holds the area of the largest 
portion of the window encountered so far, as DeviceLoop iterates through the 
screens. The windowBounds field is the portion of the window that's currently visible 
on the desktop* 


THE ZOOMTHEWINDOW ROUTINE 

About 90% of the code in Zoom'The Window executes only when the window is to be 
zoomed to the standard state. The routine starts by setting up the current graphics 
port and getting some frequently used fields out of the window record* 


void ZoomTheWindow(WindowPeek theWindow, short zoomState, 

CalcIdealDocumentSizeProcPtr calcRoutine) 


{ 


ZoomData 

Rect 

Rect 

Rect 

GrafPtr 

RgnHandle 

GDHandle 

short 

short 

short 


zoomData; 

newStandardRect r scratchRect, screenRect, portRect; 
contentRegionBoundingBox, structureRegionBoundingBox; 
deviceLoopRect; 
currentPort; 

scratchRegion, contentRegion, structureRegion; 
mainDevice; 

horizontalAmountOffScreen, verlicaLAmountOffScreen; 
windowFrameTopSize, windowFrameLeftSi z e; 
win dowFr ameRightsize, windowFrameBo11omSi z e ; 


GetPort{&currentPort); 

SetPort{(WindowPtr) theWindow); 
contentRegion = GetWindowC 0 ntentRegion(theWindow); 
structureRegion = GetWindowStruetureRegion(theWindow); 
GetWindowPortRect(theWindow, fcportRect); 
contentRegionBoundingBox = (**contentRegion).rgnBBox; 
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structureRegionBoundingBox = (**structureRegion).rgnBBox; 
windowFrameTopSize = contentRegionBoundingBox.top - 

structureRegionBoundingBox * top; 
windowFrameLeftSize - contentRegionBoundingBox*left - 

structureRegionBoondingBox.left; 
windowFrameRightSize - structureRegionBoundingBox.right - 

contentRegionBoundingBox.right; 
windowFrameBottomSize = structureRegionBoundingBox.bottom « 

contentRegionBoundingBox.bottom; 

Determining the proper screen* The code then determines which screen contains 
the largest portion of the window, as follows: 

// If the window is being zoomed to the standard state, calculate the 
// best size to display the window's information * 
mainDevice = GetMainDevice(); 
if (zoomState == inZoomOut) { 

zoomData.screenWithLargestPartGfWindow = mainDevice; 
zoomData.largestArea - 0; 

// Get the portion of the window that's on the desktop. 
scratchRegion = NewRgnf); 

SectRgn(GetGrayRgn(), contentRegion , scratchRegion); 
if (EmptyRgn(scratchRegion)) 

zoomData.windowBounds - structureRegionBoundingBox; 
else 

zoomData.windowBounds - contentRegionBoundingBox; 

// Use DeviceLoop to walk through all the active screens to find the 
// one with the largest portion of the zoomed window, 
deviceLoop Rect = z oomDa t a.windowflounds; 

GlobalToLocal((Point *}sdeviceLoopRect); 

GlobalToLocal((Point *}sdeviceLoopRect«bottom}; 

RectRgn(scratchRegion, sdeviceLoopRect}; 

DeviceLoop(scratchRegion, &CalcWindowAreaOnScreen, (long) szoomData, 
(DeviceLoopFlags) singleDevices); 

DisposeRgn(scratchRegion); 

screenRect = (* *{zoomData * screenWithLargestPartOfWindow})* gdRect; 

// If the window will be zoomed to the main screen, change the top 
// of the usable screen area so that the window’s title bar won't be 
// placed under the menu bar. 

if (zoomData.screenWithLargestPartGfWindow = mainDevice) 
screenRect,top +~ GetMBarHeight{); 
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ZoomTheWindow sets up default values in the ZoomData structure so that the 
window will zoom to the main screen by default* Normally, the content area of the 
window is used to determine the area of the window' that’s on each screen. However, 
if the user has the window positioned such that only the title bar (or a portion of the 
title bar) is visible on the desktop, the structure region of the window is used to 
determine the screen that contains the largest portion of the title ban 

One of the lit tie-known facts about the universe is that inspiration actually comes 
from subatomic particles flying around in deep space. These particles occasionally hit 
a sentient brain, resulting in a flash of inspiration. One of these events resulted in the 
use of DeviceLoop to iterate through the list of active screen devices* (Of course, this 
means that the zooming code requires System 7; for a System 6 alternative to 
DeviceLoop, see “Graphical Truffles: Multiple Screens Revealed’’ in develop Issue 10.) 
The CalcWindowAreaOnScreen routine is the DeviceLoop drawing procedure. The 
ZoomData structure is passed to DeviceLoop as the user Data value, and the 
DeviceLoop flags are set so that DeviceLoop will call its drawing procedure for each 
screen device. 

Determining the ideal size for the window. After determining the proper screen 
to zoom to, the application’s callback routine is called to get back the ideal content 
size lor die window This rectangle is then anchored at the window’s current top left 
corner and expanded to include the window frame. 

// Figure out the perfect size for the window as if we had an 
// infinitely large screen* 

(*calcRoutine){(WindowPtr) theWindow, ^newStandardRect); 

// Anchor the new rectangle at the current top left corner of the 
// window. 

OffsetRect(SnewSiandardRect, -newStandardRect,left, 

-newStandardRect.top); 

OffsetRect(^newStandardRect, contentRegionBoundingBox.left r 
contentRegionBoundingBox.top); 

// Add the window frame to the ideal content rect. 
newStandardRect.top -= windowFrameTopSize; 
newStandardRect.left -= windowFrameLeftSize; 
newStandardRect.right windowFrameRightSize; 
newStandardRect.bottom +- windowFrameBottomSize; 

Fitting the ideal sire onto the screen. This is the tedious part of the code. At this 
point, newStandardRect holds the ideal size for the window being zoomed. Since a 
window in its standard state must be entirely on one screen, we ensure that the 
window fits on the screen, maintaining its ideal size if possible. 
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If the structure region is always used to will zoom to the first screen. However, since there 

calculate the screen containing most of the is content area on the second screen, the window 

window,, there's actually a scenario in which the should zoom to that screen. * 

code will zoom to the wrong screen. If the user 

has a multiscreen setup and places a window so 

that it sits across two screens, with only the title 

bar showing on one screen but a sliver of the 

content region showing on the other, and there's 

more title bar than content showing, the window 
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// If the new rectangle falls off the edge of the screen, nudge it 
U so that it's just on the screen. CalculateOffsetAmount determines 
// how much of the window is off the screen. 

SectRect(& newStandardRect, & screenRect, & scratchRect); 
if [1EgualReet{^newStandardRect, &scratchRect)) { 
horizontalAmountGffScreen = CalculateOffsetAmount( 

newStandardRect,left, newStandardRect.right, 
scratchRect.left, scratchRect.right, 
screenRect.left, screenRect<right); 
verticalAmountOff Screen = CalculateQffsetAmount( 

newstandardRect.top, newStandardRect.bottom, 
scratchRect.top, scratchRect.bottom, 
screenRect.top, screenRect.bottom); 

Offs etRect( & newStandardRect, horizontalAmountOf fScreen, 
verticalAmountOffScreen); 


} 


// If we're still falling off the edge of the screen, the perfect 
// size is larger than the screen, so shrink the standard size. 
SectRect(&newS tandardRect, & screenRect, & sc ratchRect); 
if (IEqualRect(&newStandardRect, &scratchRect)) { 

// First shrink the width. If the window is wider than the screen 
// it r s being zoomed to, just pin the standard rectangle to the 
// edges of the screen, leaving some slop; otherwise, we know we 
// just nudged the window into position, so do nothing, 
if ((newStandardRect.right - newStandardRect.left) > 

{screenRect.right - screenRect.left)) { 
newStandardRect.left = screenRect.left + kNudgeSlop; 
newStandardRect.right = screenRect.right - kNudgeSlop; 

if ((zoomData.screenWithLargestPartOfWindow = mainDevice) && 
[newStandardRect.right > {screenRect.right - klconSpace))) 
newStandardRect.right = screenRect.right - klconSpace; 

} 

// Move in the top of the window. As with the width of the 
// window, do nothing unless the window is taller than the 
// height of the screen. 

if ((newStandardRect.bottom - newStandardRect.top) > 

(screenRect.bottom -screenRect.top)) { 
newStandardRect.top = screenRect.top + kNudgeSlop; 
newStandardRect.bottom = screenRect.bottom - kNudgeSlop; 

> 
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// We've got the best possible window position. Remove the 
// frame, slam it into the WStateData record and let ZoomWindow 
// take care of the rest. 
newStandardRect.top += windowFrameTopSize; 
newStandardRect.left += windowFrameLeftSize? 
newStandardRect.right -= windowFrameRightSize; 
newStandardRect.bottom -= windowFrameBottomSize; 
SetWindowStandardState(theWindow, ^newStandardRect); 

} //if (zoomState == inZoomOut) 
else 

GetWindowUserStafe(theWindow, &newstandardRect }; 

We call Gal culateOffsetAmount to determine how much to nudge the window if it 
falls off the edge of the screen in its ideal size. After nudging the window, we double 
check to see if the window is entirely on the screen- If it still isn’t, that means that the 
ideal size of the window is larger than the screen that it’s zooming to T so the window 
has to be shrunk to fit on the screen. The code shrinks the window so that there’s a 
small area of slop space between the edge of the window and the screen boundary. 
Additionally, if the screen that the window is zooming to is the main screen, space is 
left for the menu bar and a column of Finder icons. 

After all that, newStandardRect contains the best size for the window for that screen. 
After we remove the window frame, the stdState field of the WStateData record can 
be filled with this rectangle. 

There’s also the simple case of zooming to the user state. Since the Window Manager 
takes care of keeping the userState field of the WStateData record up to date, that 
rectangle is easy to get. 

Zooming the window. Finally, all that’s left to do is to actually zoom the window. 
One final optimization that can be performed is that if t he top left corner of the 
window hasn’t moved, Size Window can be called instead of Zoom Window, reducing 
the amount of redrawing that needs to he done. The window’s dipping region is reset 
to be the size of the window* to ensure that the window’s contents are entirely erased 
before Zoom Window is called. 


// If the window is still anchored at the current top left corner, 
// resize it. 

if ((newStandardRect.left == ContentRegionBoundingBox.left) && 

(newStandardRect.top == contentRegionBoundingBox.top)) { 

OffsetRect(&newStandardRect, -newStandardRect.left, 
-newStandardRect.top ); 

SizeWindowf(WindowFtr) theWindow, newStandardRect.right r 
newStandardRect.bottom, true); 


} 
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else { 

scratchRegion = NewRgn{); 

GetClip(scratchRegion); 

ClipRect(sportRect); 

EraseRect(sportRect); 

ZoomWindow((WindowPtr) theWindow, zoomState, false); 
SetClip(scratchRegion); 

DisposeRgn(scratchRegion); 

} 

SetPort(currentPort); 


THE CALCWINDOWAREAONSCREEN ROUTINE 

Calc WindowAreaOnScreen, the DeviceLoop drawing procedure for the zooming 
code, doesn’t actually do any drawing, but instead simply calculates the area of the 
window that’s on a screen. If there’s more content area on one screen than any of the 
other screens that have been encountered so far, CalcWindowAreaOnScreen saves 
the GDHandle of this screen in the ZoomData structure as the potential screen to 
zoom the window' to. 

pascal void CalcWindowAreaOnScreen(short depth, short deviceFlags, 

GDHandle targetDevice, long userData) 

{ 

Ipragma unused (depth, deviceFlags) 

ZoomDataPtr zoomData = (ZoomDataPtr) userData; 
unsigned long windowAreaOnScreen; 

Rect windo wPortionOnScr e e n; 

// Find the rectangle that encloses the intersection of the screen and 
// the document window. 

SectRect(&(zoomData->windowBounds), &((* *targetDevice).gdRect), 
SwindowPortionOnScreen); 

// Offset this rectangle so that its right and bottom are also its 
// width and height. 

OffsetRect(^windowPortionOnScreen, -windowPortionOnScreen•left, 
-windowPortionOnScreen.top); 

// Calculate the area of the part of the window that is on this 
// screen. 

windowAreaOnScreen “ windowPortionOnScreen,right * 
windowPortionOnScreen.bottom; 

// If this is the largest area that has been encountered so far, 

// remember this screen as the potential screen to zoom to. 
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if (windowAreaOnScreen > zoomData->largestArea) { 
zoomData->largestArea = windowAreaOnScreen? 
zoomData->screenWithLargestPartOfWindow = targetDevice; 

} 

} 

THE CALCULATEOFF5ETAMOUNT ROUTINE 

The zooming code calls the CalculateOffsetAmount routine to calculate the number 
of pixels the window needs to be nudged to be entirely on die screen. This routine 
works in one dimension at a time, so ZoomTheWIndow calls it twice, once for the 
width of a window and once for the window's height. If CalculateOfisetAiuount 
determines that the window is larger than the screen, it returns 0 for the offset, since 
the window will be resized later. 

short CalculateOffsetAmount(short idealStartPoint, short idealEndPoint, 

short ideaiOnScreenStartPoint, short idealOnScreenEndPoint, 
short screenEdgel, short screenEdge2) 

{ 

short offsetAmount; 

// Check to see if the window fits on the screen in this dimension, 
if ((idealStartPoint < screenEdgel) && (idealEndPoint > screenEdge2)) 
offsetAmount = 0; 

else { 

// Find out how much of the window lies off this screen by 
// subtracting the amount of the window that's on the screen from 
// the size of the entire window in this dimension. If the window is 
// completely off-screen, offset the window so that it's placed just 
// on the screen. 

if ((ideaiOnScreenStartPoint - idealOnScreenEndPoint) == 0) { 

// See if the window is lying to the left or above the screen, 
if (idealEndPoint < screenEdgel) 

offsetAmount - screenEdgel - idealStartPoint + kNudgeSlop; 
else 

II Otherwise, it's below or to the right of the screen. 
offsetAmount = screenEdge2 - idealEndPoint - kNudgeSlop; 

} 

else { 

offsetAmount = (idealEndPoint - IdealStartPoint) - 

(idealOnScreenEndPoint - ideaiOnScreenStartPoint); 

II If we T re nudging, add slop pixels, 
if (offsetAmount J= 0) 

offsetAmount += kNudgeSlop; 
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// check to see which side of the screen the window was falling 
// off of, so that it can be nudged in the opposite direction* 
if (idealEndPoint > screenEdge2) 
offsetAmount = -offsetAmount; 

> 

} 

return offsetAmount; 

> 

CalculateOffsetAmount determines the nudge amount by calculating the amount of 
overlap of two line segments. The first line segment, described by the idealStartPoint 
and idealEndPoint parameters, is the width or height of the window being zoomed. 
The second line segment, described by the ideaiOnScreenSrartPatnt and 
idealGnScreenEndPoint parameters, is the part of the window's width or height that 
is on the screen the window will be zoomed to. The number of pixels the window will 
be nudged is the difference between the lengths of these two line segments, plus some 
slop. If the length of the second line segment is 0, the window is entirely off the 
screen that it will be zoomed to. In this case, CalculateOffsetAmount will return the 
number of pixels the window w ill have to be nudged to be just on the screen. A third 
line segment, describing die screen width or height, is used to check whether the 
window is larger than the screen and to determine the direction to nudge the window. 

ZOOMING AWAY 

The code presented in this article takes care of most of the work of zooming 
windows. All your application needs to do is supply the code chat determines the ideal 
size for your windows. Hopefully, many more applications will implement proper 
zooming behavior in the near future. This will make the people in the offices around 
me especially happy, since ids one less thing VU have to complain about. 


RECOMMENDED READING 

* "DeviceLoop Meets the Interface Designer" by John Powers, develop Issue 1 3. 
How to use Device Loop the correct way. 

* Makmg It Macintosh: The Macintosh Human Interface Guidelines Companion 
(Apple Computer, 1 993). Anyone who wants to write programs on the Macintosh 
should be required to go through this CD first, APDA #R0450LL/A. 

* Sourcery by Terry Pratchett (Signet, 1989), Find out about inspiration particles, 
maglcons, and other subatomic particles and how they interact with ducks. 
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TEN TIPS 
FOR GAME 
DEVELOPERS 


BRIGHAM STEVENS 


In this column I’ll give some general tips that are 
targeted at game developers but can in fact benefit 
any Macintosh application. Many of the tips are 
illustrated in the accompanying sample code (CopyBits 
ColorKarma) on this issue’s CD, If you’re considering 
writing a game for the Macintosh, or you want to 
improve your existing game or other application, these 
tips are for you. Here they are at a glance; 


of all sorts. Hit Macintosh games have sold over 60,000 
copies, and users are clamoring for more. If you walk 
into a software store, though, you’ll notice that there 
isn’t a very large selection of Macintosh game and 
entertainment software. Now is the time to take 
advantage of die lack of competition and get into the 
entertainment market with your games, 

2. Bypass QuickDraw wisely. 

Applications that bypass QuickDraw by accessing video 
memory directly may not work on future Macintosh 
platforms. The Macintosh is evolving, and some of the 
changes may be in the bus architecture, causing 
applications dial write to video memory to break. 

We’re not saying this is going to happen any time soon, 
but it’s a good idea to be ready for it now r so that your 
product will last in the marketplace, 

A good compromise is to draw with custom drawing 
code into an off-screen GWo rid, and then use 
CopyBits to transfer it to the screen. This avoids 
accessing hardware directly, and will always work. 


1. The Macintosh gaming market is wide open, 

2. Bypass QuickDraw- wisely, 

3. Use CopyBits correctly. 

4. Scroll graphics smoothly, 

5. Doni synchroni ze wi th the VBL intemipt, 

6. Use Sound Manager 3.0. 

7. Learn when to use (or not use) Apple events. 

8. Use the Time Manager. 

9. Use the Memory Manager effectively. 

10. Use a compatible copy-protection scheme (if any). 


If you must w rite directly to the screen, ids important 
to follow the guidelines set forth in “Graphical 
Truffles: Writing Directly to the Screen” in develop 
Issue 11, which states that you should always have a 
QuickDraw version of your code. If your program uses 
QuickDraw (or QuickDraw GX), it will always be 
compatible with every future Macintosh platform. 

If you do bypass QuickDraw, your application should 
time the custom drawing code versus QuickDraw at 
run time, and then choose the fastest routines. This 
way, the fastest code will be used in cases where your 
code is running on a system that has an accelerated 
version of QuickDraw, or perhaps a different CPU 
altogether. 


THE TIPS IN DETAIL 

/. The Macintosh gaming market is wide open , 

The Macintosh has infiltrated the homes, offices, and 
schools of every continent on the planet, and it has 
matured enough to be ready for entertainment software 


3, Use CopyBits correctly. 

I’ve heard many developers say that CopyBits is slow, 
that it can’t achieve the frame rates needed to do good 
games. If you use CopyBits correctly, however, you can 
achieve a high animation frame rate. 
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BRIGHAM STEVENS (Interne! vikingmind@ao3.com) Since 
you lost sow Brigham here, he has spoken at ihe Worldwide 
Developers Conference on Macintosh game development, moved 
to Son Francisco, jumped out of o perfectly good airplane, become 
addicted to flight simulators, spent 160 hours in a car with no 
stereo, tossed his cookies on the steps of the Smithsonian Air and 
Space Museum in Washington DC, quit Apple to start a game 
deveiopment/consultifig company in San Francisco, and become a 
vampire. You'll see some games from him later on rn 1 994. * 
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Understanding all of the factors that affect CopyBits 
performance is critical to achieving high animation 
frame rates and still having processor bandwidth left 
over for the rest of the game. The following tips on 
CopyBits speed have been collated from many different 
sources, including Technical Notes, sample code, and 
other tomes of QuickDraw knowledge. (See also tip 4 
below.) 

* CopyBits is more efficient with wider images than 
with tall ones. 

* CopyBits is more efficient with rectangular 
transfers, with no mask region. 

* CopyBits is more efficient when the source and 
destination have the same color table, and even 
better when die ctSeeds of the color tables are the 
same. (The accompanying sample code shows how 
to use the Palette Manager and how to set up the 
color tables in your application window' and off¬ 
screen GWorld.) 

* CopyBits with a mask region is faster than either 
CopyMask or CopyDeepMask, Convert your masks 
to QuickDraw regions and then use CopyBits. (See 
the CopyBits vs. CopyMask snippet on this issue's 
CD.) 

* CopyBits is faster when the transfer source and 
destination are long-word aligned, especially on an 
68040- based M aci ntosh. 

For more details on these principles, see the Tech Note 
“Of Time and Space and _CopyBits,” 

4. Scroll graphics smoothly. 

This tip applies to games with scrolling maps, painting 
programs, and any application that needs to scroll 
window content quickly and smoothly. 

Many Macintosh applications suffer from dickering 
scrolling, caused by erasing the previous image before 
drawing the new image. To reduce flicker, you should 
redraw only the parts of the screen that change; don't 
erase anything first, unless absolutely necessary. When 
you're designing your scrolling code or animation 


engine, the philosophy to adopt is that every pixel 
should be touched only mice . 

Another technique is to buffer your graphics into an 
off-screen GWorld: make all changes in the GWorld 
and then transfer the image to the screen w r ith 
CopyBits, This can be slower, because the image is 
drawn twice, but it results in an especially smooth 
update. An example of a game that uses CopyBits in 
this way is MacPIay’s Out of This World. This game 
draws into an off-screen GWorld using custom 
polygon-rendering code (thus ensuring a high frame 
rate); then, when the image is completely rendered, it's 
transferred to the screen with CopyBits (ensuring 
compatibility with future video hardware). For more on 
this subject, see “Graphical Truffles: Animation at a 
Glance” in develop Issue 12 and “Drawing in GWorlds 
for Speed and Versatility” in Issue 10, 

There’s another method that isn't as smooth but uses 
less memory, and that is to use ScrollRect, ScrolIRect 
was changed in System 7: if you pass nil for the 
updateRgn parameter of ScrolIRect, it won't erase the 
area that has been uncovered, and you can then use 
CopyBits in a second step to copy in the new bits. (In 
System 6, ScrolIRect will erase the area you’re scrolling 
out of, causing the screen to flicker more.) 

The sample code demonstrates these techniques, 
showing the tradeoffs between memory footprint and 
smoothness/apparent speed. 

5, Don V synchronize with the VBL interrupt* 

Many developers have w anted to synchronize 
animation with the vertical blanking (VRL) interrupt to 
eliminate tears w hen the next frame of animation is 
drawn before the display hardware has completed the 
previous frame. It's possible to eliminate tears from 
small-sized animations, hut the overall application will 
run more slowly because you'll he spending time 
waiting for the VBL period to start. This results in a 
much lower animation frame rate, and the application 
also loses processing pow er for the rest of the program. 
Note diat QuickTime does not synchronize with the 
VBL interrupt. 
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For more on VBL interrupts, see the Guide to Macintosh 
Family Hardware , second edition.* 
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Another headache to consider with respect to 
synchronizing with the YT3L interrupt is that displays 
have different refresh rates, and each one’s actual VBL 
period has a different length. This means that for your 
program to have accurate frame rates on different 
monitors, you’ll have to time the refresh rate of the 
display you’re animating on. 

To work around not being able to synchronize with 
the Y\BL interrupt, you should try to interleave the 
animation processing so that you’re never updating too 
many objects at one time. The Time Manager w ill 
allow you to break the processing up into separate tasks 
(see tip 8). If you’re getting tears on objects, consider 
using fewer objects or smaller ones, 

6 , Use Sound Manager 3,0. 

The Macintosh Sound Manager has recendy been 
enhanced (version 3.0). It now r can efficiently handle 
as many sound channels as memory and processor 
bandwidth can take. This means four channels on a 
Macintosh LC (which used to handle only one channel) 
and up to 16 or more on higher-end platforms. As a 
result, your application can play sound and still have 
enough CPU bandwidth for other animation and 
processing. The sample code demonstrates multiple 
sound channels playing asynchronously while 
animating an image. Also see “Somewhere in 
QuickTime: What’s New With Sound Manager 3.0” 
in develop Issue 16 and “The Asynchronous Sound 
Helper” in Issue 11* 

Many bugs have been fixed in Sound Manager 3.0. 

You can now open a sound channel at the start of your 
program and then continuously use SndPlay to play 
sounds through it, without disposing of the channel 
between sounds. Previous versions of the Sound 
Manager had problems playing sampled sounds like 
this, so many developers adopted the technique of 
allocating and disposing of a new sound channel for 
each sound played. 

On the AV Macintosh models, the Sound Manager uses 
the DSP. This requires the DSP Manager to load a new r 
component every time you open a new channel, and 


may require disk access. So if you’re running with 
Sound Manager 3.0 you should not open and close a 
sound channel for each sound played; doing so will 
cause your application to perform less than optimally, 
especially on die AY 7 models. 

See the source code file GameSounds.c, wdiich is part 
of the CopyBits ColorKarma sample, for an example of 
a unit that manages asynchronous sound. If Sound 
Manager 3.0 or later is present, the code opens die 
sound channels at initialization and closes them when 
the program quits; otherwise it opens and closes the 
channels as sounds are played. 

Sound Manager 3.0 also adds a new routine, named 
GetSndHeaderOffset, that makes it easier to use a 
bufferCmd to play sounds. Using a bufferCmd is faster 
than using SndPlay. See the sample code on the CD for 
an example. 

Note that the sample code doesn’t store the 
application’s AS register as part of the callback 
command, so that the interrupt code can set the flag 
associated with the channel. Instead it just stores a 
pointer to the flag. This allows the interrupt-time 
callback to he very small, since it doesn’t have to save, 
setup, and restore AS; it just dereferences the pointer 
and sets the flag directly. The sample code gives an 
example of playing a sound asynchronously with a 
completion callback. I use this technique in just about 
any interrupt-time callback code I write, including 
VBL tasks, Time Manager tasks, and Device Manager 
completion routines. 

If you don’t use the Sound Manager at all, you’re taking 
an unnecessary compatibility risk. Apple has always 
recommended against accessing the sound hardware 
directly. Applications that violate this nde have broken 
in the past, and they will break again. 

7. Learn when to use (or not use) Apple events. 

Apple events have simplified inter application 
communication, making it easy to add value to your 
application. A game played against live human players 
is often more fun than a game played against a 
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Sound Manager 3.0 is available For licensing, so you can 
distribute it with your products to ensure that your customers and 
applications will receive its benefits. You can reach Apple's 
software licensing department at AppleLink 5W.LICENSE, * 


develop Issue \7 





computer. Just about every night you’ll find some 
Apple engineers huddled over their computers playing 
Bolo, Spaceward Ho!, or other network games. 

Consider Velocity’s Spectre, a network tank game that 
has been veiy successful. Spectre doesn’t use Apple 
events; it uses custom DDP (datagram delivery 
protocol) socket listeners at the lowest level of 
AppleTalk to achieve high performance. But if your 
game doesn’t require the same level of performance, 
you may benefit from the ease of use of Apple events. 

If you require more performance than Apple events 
can provide, one option is to use the PPC Toolbox 
directly, which will allow you to still remain a step 
removed from direct AppleTalk. See the PPC Toolbox 
chapter of Inside Macintosh Volume VI for more 
information. 

If you require even more performance, you can use 
AppleTalk Data Stream Protocol (ADSP) directly, or 
one of the other AppleTalk protocols. ADSP is a 
higher-level protocol that will allow you to do block 
transfers and not worry about losing packets and packet 
order. 

It’s hard to determine which networking protocol to 
use ahead of time. From my experience in using Apple 
events to synchronize animation and events between 
two Macintosh computers, I would say that if your 
game is a more than two-player, real-time arcade game, 
Apple events would probably not be the best solution. 

If your game is a turn-based strategy-type game, like 
Spaceward Ho!, Ro bo Sport, Strategic Conquest, and 
many others, Apple events will work very well for you, 
no matter how many players are in the game. 

For a simple example of using xApple events as a game 
messaging system, see ZAM l.alS on the CD. 

8, Use the Time Manager. 

The Macintosh Time Manager is very useful for game 
developers. Animation code often needs a heartbeat, to 
synchronize the timing and updates of every object. 


The Time Manager lets you break dow n your code into 
discrete tasks that run at a steady rate. This allows you 
to write modular code that updates smoothly. 

One limitation of the Time Manager is that tasks fire at 
interrupt time, so they can’t do much more than set a 
flag to inform the regular event loop that it’s time to do 
something. The sample code on the CD shows how to 
place a wrapper around the Time Manager that allows 
you to execute tasks at non-interrupt time. 

9 . Use the Memory Manager effectively. 

The Macintosh Memory Manager is very flexible, and a 
boon to most application programmers. However, for 
the game programmer it can be a performance problem 
unless it’s used wisely In a game, you should 
preallocate as much of your memory as possible. If 
you’re using a dynamic object allocation scheme, you 
should design one that preallocates the objects and 
keeps track of which ones are in use or not. If you have 
many allocated blocks in a heap and then request a new f 
one, you could send the Memory Manager into 
thrashing mode where it will try to move many blocks 
around to make space. This can cause your animation 
to be jerky or your wdiole game to freeze for an instant. 
So the best thing to do when performance matters is to 
minimize your use of the Memory Manager. 

To minimize Memory Manager use, you should not 
only allocate as much of your memory up front as 
possible but also avoid using relocatable blocks unless 
absolutely necessary This means avoiding game 
architectures that rely on the Memory Manager for 
dynamic object allocation. Definitely allocate your 
nonrclocatable blocks first, and allocate handles later. 
This prevents heap fragmentation and avoids sending 
the Memory Manager into a tail spin. 

Re aware that some parts of the Toolbox, like Apple 
events, expect Memory Manager structures. However, 
if the rest of the program’s memory is allocated wisely 
to prevent heap fragmentation, even these allocations 
will happen quickly with no impact on game 
performance. 
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10. Use a compatible copy-protection scheme (if any). 

It’s a matter of great controversy whether software 
should be copy-protected at all. No software protection 
scheme on the Macintosh lias ever survived the talented 
efforts of Macintosh hackers. There's always someone 
who w ill defeat your copy protection, no matter how 
convoluted it may be. There are many who consider 
such protection a puzzle and a challenge to break, so by 
putting it in you may be inviting piracy. 

But if you do decide you want some level of protection 
on your game, we strongly recommend against a disk- 
based protection scheme, which is guaranteed to break 
your program. Instead, we recommend using one (or a 
combi nation) of the methods described here. 

One method is to use serial numbers: when the 
software is installed, ask the user to enter the serial 
number from the disk label, and then imprint the 
software with the person’s name. Another method 
involves requiring the user to enter a password from 
the manual every once in a while. If you do this, it’s a 
nice touch to allow users who send you the registration 
card to disable die password dialog; once you have the 
registration card, you can link the customer to a serial 
number. 

Consider also making the following checks: At 
installation time, use Gestalt to determine the 
characteristics of the machine you’re installed on, and 
save these to your preferences file. Also, use FindFolder 
to record the directory ID of the System Folder, which 
is the same until a new System Folder is created. Every 
time your application starts up, make the same Gestalt 
and FindFolder calls to check whether you’re running 
on the same machine; if not, have the user reinstall the 
software and reenter the serial number, or reenter the 
password from the manual. 

These techniques are the most compatible way to both 
protect your sales and minimize the kind of frustration 
customers experience with other password- or disk- 
based copy protection systems. 


ARE YOU GAME? 

That’s not all! To help Macintosh game developers 
share dps, tricks, and information, Apple has set up the 
Game Development Discussion folder on AppleLink 
(in Developer Support: Developer Talk). This board is 
read by Macintosh game development companies, 
other developers, and Apple engineers on a daily basis. 
Also, there’s a folder on this issue’s CD, called Game 
Development, that contains special resources Apple has 
put together to aid all game developers. 

So if you’re tired of die scant choices on the Macintosh 
Entertainment shelf in your local software store, do 
something about it: w rite some games! 
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* "Drawing in GWorlds for Speed and Versatility" 
by Konstantin Othmer and Mike Reed, develop 
Issue 10. 

* Guide to Macintosh Family Hardware , 2nd ed. 
[Addison-Wesley, 1990). 

* Snow Crash i, by Neal Stephenson. A fast-paced 
book to keep you up late at night. Stephenson 
says this book was inspired by the original 
Macintosh Human Interface Guidelines. (Imagine 
what he would have done if he'd had the new 
improved editionI) 
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If you create a demo version of a game by commenting out 
code or imposing o time limit to game play, be aware that these 
kinds of demos are often hacked into full-blown pirate applications. 
We strongly suggest that when you create a demo version, you 
take out all nanessential pieces of code and sufficiently cripple the 
remaining software (so that a hacker can't simply paste in missing 
resources to get a full, unprotected copy].* 


Thanks to Konstantin Othmer, Jim Reekes, and John Wang for 
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contributed to the information in this column, including (but not 
limited to) C. K. Houn, Tony Myles, Craig Fryar, Mike Schlachter, 
Bill Dugan of Interplay Productions, and the rest of the developers 
I've worked with over the past couple of years. * 
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Q 


In QuickDraw GX, if the QuickDraw clipping region of a window (set by 
SetCIip(aRgn)) is not rectangular the shapes drawn to the window's viewPonare 
sometimes dipped incorrectly. Is this a bug? 


A This is not a bug. QuickDraw GX doesn't honor any at the QuickDraw 
clipping regions except the one that's connected to a viewPort, created by 
calling the GXNew Window View Port routine. 


MACINTOSH 
Q & A 


Here's why: So that QuickDraw GX can draw into viewports associated with 
windows, it patches the Window Manager. When the user moves a window, or 
when your application calls BeginUpdate and End Update, QuickDraw GX 
updates the viewPort caches and dip shape* The clip shape is set to the visRgn 
of the window. However, all other QuickDraw regions are ignored. 


If you want to do some smart window dipping, you can. But you can't play 
directly with the viewPort attached to the window: that viewPort is maintained 
by the QuickDraw GX system and is therefore off limits to the application. (If 
you do try to manipulate it, you'll receive an error.) You need to attach a child 
viewPort to the window's viewPort; then you can convert the QuickDraw 
region you want to clip to into a GX shape (with the GX Translator) and set the 
child viewports clip shape to this new shape. Your QuickDraw' GX shapes will 
then be clipped correctly 


Q Calling GXSetStykRunControls on a layout shape with the “track ''fieId set doesn't 
always have any visible effect , although the track value is always safely stored in the 
layout shape and can be retrieved with GXGetStyle R un Con f ro Is. You can see this in 
GX Write by adjusting the track kerning of some Tekton text: that works fine. If you 
switch to the Hoefler font* however ,; no track kerning isperformed, Can you explain 
this? 

A When a track kerning value is specified, QuickDraw' GX looks to the tables in 
the font to see how the kerning should be performed. A narrow text face with a 
large x-height, like Avant Garde, can probably take much tighter track kerning 
than something like Hoefler Italic can; only the font designer really knows how 
the kerning should behave. The font designer tells QuickDraw r GX how to do 
track kerning by setting values in the trak' table of the font. This table contains 
one or more “reference points" — values between -2 and 2 — each of w hich 
tells how much to adjust space between the glyphs for any number of point 
sizes* If the specified track kerning value lies between reference points, 
QuickDraw GX interpolates accordingly 

Hoefler Italic contains only one reference point — “norma!” kerning (value 0). 
It does contain values for several different point sizes, but the font designer 
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doesn’t want the face more tightly or loosely kerned than in his original design. 
Since there’s only one 'trak' point, QuickDraw GX winds up interpolating those 
entries with themselves and nothing really happens for the values you specify in 
the run controls. As you’ve noted, those values are still there, and they wnuld be 
used if you switched those runs to a different text face, but they’re having 
exactly the effect Jonathan Hoefler wanted — none at all. 


We do developing a QuickDraw GX printer driver for a 24-hit continuous-tone device. 
First , what should halftone fields he set to for a continuous-tone device (are they 
ignored?). Second, do we have to override GXDefaultPrinter and GXDefault Job? The 
ImageWriter example shows building a default colorset inside GXDefaultPrinten 

The answer to your first question is that you can stop QuickDraw GX from 
using the halftone information by setting the gxDontSetHalftone flag in the 
plane flags field of each plane in the ’rdip 1 resource. That’s it— the halftone 
fields will be ignored. 

The messages GXDefaultPrinter, GXDefaultDesktopPrinter, GXDefaultJob, 
GXDefaultPaperTvpe, and GXDefaultFormat may be appropriate for your 
driver to override in order to modify default objects. You don’t need to override 
these messages unless you have a reason to change the default object. 

The ImageWriter driver with QuickDraw GX adds a list of view devices that 
are appropriate for the printer that’s being used. Specifically, it adds a 144-dpi 
black-and-white view device and, if color is available, a 144-dpi color view 
device* If the driver didn’t add these, the default printer view device {24-bit at 
72 dpi) would be used. Overrides of a GXDefaultxxx message typically forward 
the message first to obtain the default object, and then modify that object as 
needed. So if you want more than one view device to be installed by your driver, 
you should override GXDefaultPrinter. That’s what the ImageWriter driver is 
doing. 


What is the correct way to recognize Power lalk letters? Is it by checking for the file type 
‘Ittr' or by looking at Finder flag bit 0x0200? Should I be saving letters as type 'Ittr or 
as my own file type, and should I be setting the bit? 

The correct way of checking whether a particular document is a letter is to 
check the isLetter bit of the Finder info field. It T s bit 9, mask 0x0200, and 
occupies the space formerly used by the “changed” hit. 

Cheeking for file type 'Ittr’ doesn’t w r ork, since letters may have whatever file 
type the sending application desires. In fact, an application may support 
multiple letter types, and may have a different file type and icon for each type. 






This allows additional flexibility, since an application may have some idea what 
content the letter contains by checking its type, even before opening the letter. 

Note that when your application saves a letter to disk, nothing special needs to 
be done with either the Finder Hags or the file type to ensure that the Finder 
notices that the file created is a letter. SMPBeginSave and SMPEndSave will 
automatically set the isLetter bit for you, and the Finder will realize from this 
bit that your file is indeed a letter. 

One final piece of information: Since letters may have a file type other than 
'lttr, an additional hook was added to the Finder drag and drop mechanism to 
allow applications to have any letter drop-opened on them, regardless of the 
letter's file type. If you add a BNDL/FREF pair with the type r ltr*' to your 
application, the Finder will highlight your icon whenever any letter is dragged 
over it. This mechanism works in the same way that '****' does for the universal 
drag and drop w ildcard. 


Can we use a different A5 world with QuickTime? Our plug-in architecture uses A 5 
for global access , but we allow the A5 world to move. QuickTime does?? V seem to 
appreciate this and does?! V think that EnterMovies has been called after the A S world 
moves. We currently work around this by locking down our AS world but would rather 
not. Is locking down the AS world even good enough? 

You can use a different A5 w r orld with QuickTime. QuickTime allocates a new 
set of state variables for each A 5 w r orld that’s active when EnterIVlovies is called 
However, since QuickTime uses A5 to identify each QuickTime client, if you 
move your plug-in’s A5 w r orld QuickTime w ill no longer recognize that you've 
called EnterMovies for that client. So you can use a different A5 world, but 
you'll have to lock it down. 


We 're trying to display a QuickTime movie in a frame that can be panned , cropped, 
and overlaid by other objects . The movie controller doesn't seem to understand that the 
badge may lie entirely outside the frame. Is there some way to tell the movie controller 
where to place the badge? 

Unfortunately, QuickTime isn't flexible about this. The code that positions the 
badge calculates it from the bounding box of the movie region, and insets it six 
pixels from the left and bottom. There's no sane way to work around this, other 
than not to use the standard badge, but instead use your own badge and perform 
your own badge tracking. 


Tve noticed some interesting behavior using the standard compression dialog and was 
wondering if someone could explain if to me. Fm trying to provide session-wide 





defaults for compressing sequences of images. Ifl don't prime the dialog by doing an 
SCRequestSequenceSettings, then when I do an SCCompressSequence Begin the dialog 
is displayed. Is there any way to prevent this , and to use some set of defaults (without 
using an image to derive the defaults)? 

The compression dialog components allow you to get settings with the 
SCGetlnfb call, and to set them with SCSetlnfo. The first time, you should 
display the dialog with SCRequestSequenceSettuigs, and then me SCGetlnfb to 
retrieve the settings. After that, you can apply the same parameters before 
starting a compression sequence by using SCSetlnfo. If you provide settings 
before calling SCCompressSequenceBegin, the dialog won’t he displayed; 
otherwise it wall be. See Inside Macintosh; QuickTime Components, page 3-8 and 
pages 3-15 through 3-25, for details about the format of the settings. 

Also, as you may know, you can generate default parameters that also avoid the 
dialog by using the SCDefaultPixMapSettings, SCDefauItPictHandleSettings, 
and SGDefaultPictFileSettings routines. But these do require an image. This 
way you can avoid displaying the dialog for the first sequence, and still generate 
valid settings. See Inside Macintosh: QuickTime Components , pages 3-26 through 
3-28, for more information about these routines. 

When a user pastes a movie into a movie-controller movie, the added movie is inserted 
in the top left corner of the movie. Is there a way for the user to choose where the movie 
is pasted, and if not , how can I give the movie controller or Movie Toolbox an offset to 
use rather than have the editing operations use the top left corner? 

When you paste a movie into a movie-controller movie, the movie controller 
is simply calling PasteMovieSelection to insert the source movie* All the 
characteristics of the movie are inserted, and therefore the movie is inserted in 
the top left corner of the movie. There’s no easy way to specify an offset directly 
to the movie controller* If you want to change the offset of the pasted movie, 
you’ll have to modify the movie yourself after the paste using Movie Toolbox 
commands* Once you’re done changing the movie, be sure to call 
MCMovieChanged so that the movie controller updates correctly* 

The actual modification is simple: call GetTrackMatrix, add your offset to the 
matrix, and call SetTraekMatrix. The difficulty is in determining which tracks to 
modify, since the paste may either create a new track or use an existing one. We 
recommend doing this by gathering all track indexes before the paste, and then 
comparing with the track indexes after the paste. Since most movies these days 
have just a fe^w tracks, this shouldn’t require much overhead* (But he warned: 
some movies do have a lot of tracks!) To get the track information, you can call 
GetMovieTrackCnunt and GetMovielndTrack. 






One last idea: If you don't mind changing the source movie, an alternative is to 
simply offset the source movie before the paste. 


Has Apple defined a codec type for a codec that does CCITT Group IV FAX 
compression/decompress ion? If not, how does one go about registering a brand new codec 
type with Apple? 

We’re not aware of any standard codec type for CCITT Group IV FAX. Apple 
doesn’t have any mechanism in place for registering codec types. We suggest 
that developers use the creator code for their applications, since creator codes 
are unique, as long as they register them with ns. We hope to have a better 
solution than this sometime in the future. 


When l called Gestalt with the gestaltKeyhoardlype selector and my new Apple 
Adjustable Keyboard using System 7.1,1 expected Ges talt to ret urn a response that 
warn V in GcstaltEqu.h, but instead it returned an error of-5SSO, meaning “Couldn't 
obtain response. n Is there something more I need to do? Should I expect Gestalt to 
return an error when I get new hardware? 

Gestalt is in error in not being able to identify the adjustable keyboard. Hut 
the real problem (which the adjustable keyboard exacerbates) is that die 
gestaltKeyboardType selector doesn’t really do what you want it to do. What 
you want Gestalt to do is enumerate the features of a system; however, 
gesta 1 tKeyboar tHype tells you the type of keyboard most recently touched, 
which is of limited utility. In the past, it’s been very rare to have more than one 
keyboard on a system, so the gestaltKeyboardTypc selector could give you a 
unique answer. But the adjustable keyboard is two separate keyboards — one 
for the keyboard and one for the numeric keypad so gestaltKeyboardTypc 
can’t give you a unique answer. Because of these problems, we consider this 
selector to be obsolete. 

What you need is a way to list all the keyboard devices on a system. You can use 
the ADB Manager’s GetADBInfo call to get the information for all the ADB 
keyboards connected. You’ll see two keyboards connected if the whole 
adjustable setup is installed. The first will be at address $02 (all keyboards have 
an original address of $02); the second will he at an address between $08 and 
SOF, due to ADB remapping. Your first task would be to determine which ADB 
devices are keyboards. You can do this by using CountADBs to tell you how 
many devices there are, and then having a loop that calls GedndADB for each 
device. For each device, you would test the original address field; if it’s $02, you 
have a keyboard of some type. You can then use the handler ID of the device to 
identify the keyboard. The names and device handler IDs of the three main 
adjustable keyboards and the adjustable keypad are as follows: 






U.S. standard adjustable keyboard 
ISO standard adjustable keyboard 
Japan adjustable keyboard 
Adjustable keyboard's keypad 


$10 

$11 

$12 

$0E 


Note that the keypad will usually be the one remapped and there’s no way to 
guarantee that it will be remapped to a specific address. That’s why you have to 
use CountADBs and GetlndADB to get the information. 

Someone told me recently that the glue on postage stamps is made from hone hooves 
and other mammalian unmentionables. Is this true? Pm a strict vegetarian. 

The glue used on postage stamps is not made from hooves or any other animal 
products. Although we’re not sure exactly what it is made of, we’ve been assured 
by the United States Post Office that the glue they use is vegan and kosher. 
(International readers should check with their local postal services,) 

Is there any reliable way of extracting the scaling information from a page setup record? 
We want to display a summary of the page setup in terms ofpaper size and scaling (for 
example, 8J" by 1 /", 50%) instead of virtual page size (such as 27" by 22 f ). Can we 
assume that the editText item with a numerical value is the scaling field? 

There is no reliable way to extract the scaling information. You certainly can’t 
assume an editText item in a dialog is the scaling field — it could be anything. 
Don’t assume anything about the items or their order, because printer driver 
developers are free to do whatever diey feel like, and most of them have. The 
Image Writer allows only 50% reduction, for example, so it’s a checkbox, not a 
numerical field. In some drivers such options may even be in the job dialog for 
“user convenience.” 

We’ve tried for a long time to come up with a reliable way to do this, and there 
just isn’t one. Drivers can and do store scaling values, if they support them, 
anywhere they like in the print record. You can’t compare the page rectangle to 
that returned by PrintDefauk because the user may have picked a paper size 
other than the default. (You wouldn’t want the user to choose legal paper and 
see 8.5” by ll ft , scaled 100% horizontally, 122% vertically!) This mechanism 
was designed to be transparent so that applications wouldn't have to do 
anything, but it was designed too transparently: applications can't tell what the 
scaling is even if they want to. Note that the new' printing architecture of 
QuickDraw GX actually lets you find out tilings like this. 

Pm trying to draw text to a rectangle and am using TextBox, which works fine. What 
I want to do is determine the vertical coordinates of the bottom of the text in the text 






box, I want to draw a line right under the bottom of the text, and the text is arbitrary 
in length. One time it may be a single word, other times an entire sentence that wraps 
in the rectangle. Do you know any way to calculate what / need? 

Unfortunately, you can’t do it. TextBox doesn’t leave the port in any state that 
can be counted on. However, all is not lost: TextBox is a relatively simple 
operation and can be easily duplicated with a few lines of code. If you duplicate 
TextBox, you can access the TextEdit record before it 7 s destroyed* With access 
to the TextEdit record you can easily measure the text drawn. Try die code 
below. Also see “The TextBox YouVe Always Wanted" in develop Issue 9 for a 
very flexible, fast replacement to TextBox* 


void MyTextBox(Ptr text, long length, Rect *box, short just) 

{ 

// Replacement for TextBox that will draw a line under the last 
// line of text. 

TEHandle te; 

Rect UnderRect; 

te = TEStyletEew(box, box); 

TESetJust(just, te); 

TESetText(text, length, te); 

TEUpdatefbox, te); 

UnderRect = (*box); 

UnderRect.top = TEGetHeight(32767, 0, te) + UnderRect,top; 
UnderRect,bottom = UnderRect,top + 1; 

TEDispose(te); 

FrameRect(&UnderRect); 


Q 


Is there any way for an application to mount an AppleShare volume in System 6? In 
System 7, the PBVolumeMount function allows you to do this if you have the right 
information . Is this call or a similar one supported in System 6? 


A The PBVolumeMount, PBGetVolMountlnfoSize, and PBGetVoIMoun tin fo 
calls arc all supported in System 6 if the AppleShare 3.0 or later Chooser 
extension has been installed. These versions of the Chooser extension have been 
tested back to System 6.0.4, and work fine. 


Q 


Our product needs to access the DCD signal from the modem port to function correctly 
when talking to an external modem. Most documentation doesn't say anything about 
the DCD signal being available . However, we have a hardware diagram that shows 
that pin 7 on the mini-8 connector is connected to give a DCD signal on later 
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Macintosh models. In most documentation pin 7 is shown as not connected, [spin 7 
connected to anything, so that I can wire it to the DCD signal from the modem? If so, 
how can I access the status of pin 7 to see when DCD is asserted or negated? If I can do 
this , what models of Macintosh will it work on, and will it stay like that in future 
releases? 

There is ongoing confusion regarding the Macintosh serial ports and how to 
wire them for serial operation* Macintosh serial ports are RS-422. By shorting 
the positive receive pin to ground, yon create an RS-423 port, which is an RS- 
232 emulation* The table below shows a pin-wiring schematic from die 
Macintosh DIN-8 to DB-25 RS-232 serial cable, which supports hardware 
handshake and DCD transmission (arrows show the direction of signal 
transmission): 


DIN-8 


DB 25 

HSKo 

1 —> 4, 20 

RTS, DTR 

HSKi 

2 <— 5 

CTS 

TxD- 

3—>2 

TxD 

GnD, RxD+ 

4 , 8-7 

GnD 

RxD- 

5 <— 3 

RxD 

TxD+ 

6 


GPi 

7 <— 8 

DCD 

Shield 

1 — 1 

Shield 


Notice that we connect the DCD signal to the GPi input pin. As you know, the 
GPi trace isn’t implemented on all Macintosh CPUs. Additionally, there is no 
serial driver call implemented to obtain the current state of the GPi pin* Rather 
than have a complete list of which CPUs ids connected on, you can fairly easily 
make your application dynamically find this out on a particular CPU at run 
time* So you can tell the user whether DCD from a modem can be detected on 
a particular installation, with no need for a priori knowledge. See the Macintosh 
Technical Note “Serial GPi (General-Purpose Input)" (Devices 16) for a 
description of using GPi and Gestalt* 


/ use the Open Picture, draw , Close Picture sequence to create a picture handle . Since the 
handle can be quite large , and since I dispose of it fairly quickly, it would make sense to 
allocate it in temporary memory. But I haven t found any reasonable way to do that * 
Any suggestions? Both these situations arise because my application runs in a fairly 
small (HOOK) partition * / do this so that other applications have adequate space to work 
with it , since one of my main functions is to interact with other applications using Apple 
events. However, I occasionally need more memory for a few seconds at a time * 






A 


There are two ways to cause Open Picture to use temporary memory. A simple 
way to do it is to allocate a block of temporary memory, then create a new 
heap zone in that block and make it the current zone just before you call 
OpenPicture. This will cause subsequent memory allocations to happen in your 
temporary block, and will work fine. See Inside Macintosh: Menrny for more 
information about creating heap zones. 


Another way is to replace the putPicProc, as is commonly done when spooling a 
picture to disk, and instead spool it to temporary memory. If you’re not familiar 
with picture spooling, see Inside Macintosh Volume V, page 89, which has code 
for spooling a picture to disk as its created. This is the same technique as 
documented there, only it spools the picture to temporary memory instead. 

You create a handle in temporary memory the size of a picture and fill in its size 
and picFrame fields so that it looks like a normal picture handle. In your 
putPicProc you copy ihe data in, continually resizing the handle if necessary to 
fit the data. After you call ClosePicture, remove your putPicProc; then you can 
use the temporary handle just like a normal picture. 

The advantage of this method over the first one is that you can make the picture 
as large as temporary memory will let you, and you end up using just enough 
memory. The first technique, while technically easier to implement, limits you 
to the size of the heap you initially create, and you also may use a lot more 
temporary memory than you need. If you’re able to come up with a good guess 
of how large your pictures are going to be, use the first technique; if not, use the 
second one. 


Q 


/ think I may have found a hug in the System 7 TrueType rasterizer code: under some 
clipping conditions it may trash/freeze the system inside the DrawText call Tm really 
not doing anything out of the ordinary; the key to making it die apparently lies in the 
placement of an obstructing window that just barely overlaps the text being drawn . 
Investigating the problem in Macs Bug reveals that somewhere deep in the TrueType 
rasterizer some code is trashing the A3 register and not restoring it properly. 


A 


This is a bug in QuickDraw’s text-drawing routine, introduced when support 
for TrueType was added: QuickDraw (under certain circumstances, like 
foreground not black or background not white) allocates an off-screen buffer for 
the text on the stack. If there isn’t enough stack space, the string is cut in pieces, 
and die code reentered for each piece separately. (If that still doesn’t help, no 
text is drawn at alb) The bug is that A3 is assumed to hold the port throughout 
die text-drawing code, hot when we added support for TrueType, we reused A3, 
forgetting the previous convention for the case w r here the string had to be 
subdivided. This probably won’t be fixed before the rewritten QuickDraw is 
released in PowerPC processor-based machines. 
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The workaround is to preflight available stack space before issuing text-drawing 
calls for long strings and large point sizes, and draw the string in pieces yourself 
if necessary. You may also want to allocate more stack space at startup via 

SetApplLimit{GetApplLimit() - something ); 

with something empirically determined. For a big application with a large 
minimal partition size, 16K or 32K more or less in the heap shouldn't matter; 
but it's a big win for QuickDraw’s reliability, and generally a good 
recommendation. 


/ would like to be able to determine the clock speed of any CPU I know that I could 
write a routine and calculate the time it took to execute the code , but can you tell me a 
more direct way ? 

You can use the GetCPUSpeed routine to check the current clock speed of the 
PowerBooks (after checking gestaltPow erMgrAttr to make sure that the Power 
Manager is present). This routine is documented in the Power Manager chapter 
of Inside Macintosh Volume VI (page 31-20). 

Unfortunately, there's no way to check the clock speed of other Macintosh 
models. The only thing you might be able to use as a crude way of comparing 
relative speeds is the low-memory global, TimeDBRA ($ODOO), TimeDBRA 
gives you the number of iterations of DBRA per millisecond, which can help in 
a relative speed comparison. 


A wonderful thing about MacsBug is that you can save logs , and our testers use it to log 
crashes ofimr programs under~ development. Unfortunately^ some of our more lazy 
testers just send a log without a description of how they made the crash occur. I was 
wondering if there's a way a user can enter a comment in MacsBug that will get saved 
in a log hut won V be interpreted by MacsBug. This way , users could put the whole bug 
report in one nice consolidated log , without going and editing it later in a text editor 

You can enter text into your MacsBug log by using the printf dcmd in MacsBug. 
It's similar to the C printf function. If your testers want to add anything to the 
log file, they can simply type 

printf "interesting comment that I wanted to make" 

For more on the printf dcmd, see the MacsBug 6.2 reference manual. 

I have problems linking my QuickDraw GXprinting extension when / include MPW^s 
StdClib.o, evidently because I call sprintf I was told this is because of global variables in 







the StdCliko library. Does MPW have a parallel library for use with standalone code 
-—something like THINK Cs ANSI-A4 library ? 

The problem is that two of the routines in StdCLiko use global data* You can 
get around this problem by reded a ring the problem routines in your code. First 
#S include <StdIO,h> in one of your source files or included header files* Add the 
followi ng to your source: 

sizejt fwrite[const void *, size_t t size_t, FILE *) { return 0; } 
int _£lsbuf(unsigned char, FILE *) { return 0; } 

These lines redefine fwrite and _flsbuf, the offending routines, so that they 
don't use global data (or do anything, for that matter, except return 0), Make 
sure that the object file containing the above routines appears in your Link 
instruction before StdCLib.o, since only the first declaration will be used. Of 
course, this means that you can't use the fwrite and _flsbuf routines, but its 
unlikely you’ll want to in a printing extension anyway. Also, sprintf never calls 
them. The linker will generate “duplicate symbol definition” warnings for die 
two routines, of course, unless you specify -msg nodup in your Link 
instruction. In addition, don’t forget to link with RunTimes. 

The sprintf routine is great for debugging, since you can easily get formatted 
debugger output, as follows: 

OSErr err; 

Str255 pStr; 

// Do stuff that might cause an error 


if (err) { 

pStr[0 ] = sprintf($p$tr[l] f "Error %d r \ err) ; 

DebugStr(pStr); 

} 

Also, check out the dprintf command in QuickDraw GX's GXExceptions.h file; 
it’s similar to this. 


Q 


What is the correct term for the little depression above the center of my upper lip? In 
high school we called it a ^eurvide, ” but Pm pretty sure we made that up. 


A 


The correct term is “philcrum,” Biologists debate heatedly about its real 
purpose, but there's no doubt that it makes a good place to rest the tip of your 
index finger during periods of deep thought. 
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KON & BAL'S 


PUZZLE PAGE 

WHEN MAPS 
GO BAD 


See if you can solve this programming puzzle, presented in the form of 
a dialog between Konstantin Othmer (KON) and Bruce Leak (BAL). 
The dialog gives clues to help you. Keep guessing until you ’re dotie; your 
score is the number to the left of the clue that gave you the correct 
answer. These problems are supposed to be tough. If you don V get a high 
score , at least you'll learn interesting Macintosh trivia. 



KONSTANTIN OTHMER 
AND BRUCE LEAK 


KON 


BAL 


KON 

BAL 

KON 


BAL 

KON 

BAL 

KON 

BAL 


I have a Macintosh Ufa at home with a 13-inch color monitor and an 
old Kong. 

You mean the black-and-white two-page display? That thing is out of 
production. Programmers were the only ones who bought it, and we 
already sold one to every Macintosh programmer. I’ve got one too. 

Mine’s probably older, though. Fung gave me one of the prototype 
units that were blocking the entrance to his office about five years ago. 

Does it have the stylish metal cheese grater cage around it or did you 
actually get a plastic case? 

I scored one with plastic, though it’s yellow' now from sitting in the 
sun. Anyway, now that die PowerPC workload is finally winding dow'ti, 
I’ve actually spent some time at home. I started playing around with 
Darryl’s mapping program on my fx. 

MacAtlas? 

Yeah. It’s pretty cool. The problem is I can’t open files. 

Command-O open? What happens? 

Nothing. No Standard File, no dancing bears — it’s as if I never gave 
the Open command. 

I’ve never had a problem with that program. Does the menu get 
highlighted? 
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KON 

BAL 

KON 

BAL 

TOO KON 


BAL 


90 KON 


BAL 


80 KON 

BAL 
70 KON 
BAL 


Yeah. Every once in a while you’ll see it flash. This problem happens 
systemwide; I can’t even open files in ResEdit. 

Can you drag documents onto the application icon in the Finder to 
open them? 

Yeah. Everything not related to Standard File seems to work fine. I can 
edit files, play movies — even file sharing w orks. 

What version of the system are you running? Does printing work? 

Fm running System 7.1. T can’t save and then print as recommended 
by our print shop because there’s a problem with Standard File, but 
other than that it works fine. Why? 

This one’s easy, KON. Something is locked down in your Multi Finder 
heap, so your system heap can’t grow. Standard File can’t bring in all 
its resources, so it punts. Are you running that skankv StpckltToMe 
server that Tima and Rubinowitz wrote? 

This happens just after boot and IVe got mounds of RAM now that 
I’ve removed DAL. I do a heap dump (hd) of the MtildFinder heap 
and there are no locked blocks at the bottom, so the system heap can 
grow r all it wants. Furthermore, the heap total (ht) command shows 
that there’s plenty of room in the system heap. 

Clearly this bug is limited to your home machine. I figure you have 
some slimy KON code on there that’s only half debugged — maybe a 
beta version of Wonder Print. Set an ATB on Standard File, 'PACK 1 3, 
and then try to open a document. 

I hit the A-trap, but w r hen I trace over it it just returns without putting 
up the Standard File dialog. 

Is the package getting loaded? 

Yeah. 

Since I don’t have die source to Standard File handy, I’ll use the log 
command and then the conditional step command to get a trace of all 
the instructions executed inside the package. I figure it should be fairly 
easy to spot some error condition where die code decides to bail. Since 
the _Pack3 instruction is two bytes, if the call to it is at the current PC 
address, I use the Maes Bug commands 

log MyStdFileLog 
S pc=pc+2 

to step, logging each instruction to a file and then stopping as soon as 
the trap is exited. 


131 


KON & 8ACS PUZZLE PAGE March 1994 






60 KON Wow, that conditional stepping is pretty cool. I didn’t know MacsBug 
was that sophisticated* You could have just put a breakpoint on the 
other side of the _Pack3 and stepped a zillion instructions. 

Anyway, the trace isn’t prohibitively long. Standard File preloads all 
the resources it needs to display the dialog, checking each one to see if 
it was loaded properly. When it tries to load LDEF -4000, it fails and 
hails. 


BAL 

55 KON 
BAL 
50 KON 

BAL 

45 KON 

BAL 

KON 
BAL 
40 KON 
BAL 

35 KON 
BAL 

30 KON 

BAL 


All the resources it needs must come from the System file. Check to 
see if LDEF -4000 exists in the system. 

According to ResEdit, the LDEF isn’t present in the System file* 

Compare the LDEFs in your system with a fresh installation. 

The LDEFs are all die same except one, which has a different resource 
ID. 

Well, it sounds like you’ve got a trashed System file. Copy and paste 
the bad LDEF into your system and reboot* 

Everything works fine now, but if 1 drag-install a new system, Standard 
File fads. Fixing the LDEF is addressing the symptom, not the 
problem. 

You drag the good System file over and reboot, and Standard File is 
broken again? 

Yep. 

Check the LDEF with ResEdit. 

It’s renumbered again. 

So something is trashi ng die resource map during boot. What if I boot 
with the Shift key held down to disable extension loading? 

According to ResEdit, the resource map is still trashed. 

Try dumping resources of type 'LDEF' with die command rd LDEF 
at interesting times during the boot process* 

If you hold down the Control key to enter MacsBug just after it’s 
installed, the LDEF resources are fine* If you check it again when 
you’re in the Finder, the LDEF is bad* 

So I use 


atb hopenresfile 1 ;dm @(sp+2);rd LDEF;g 

to w r 3 tch extensions load during the boot process. The command 
breaks as each extension is loaded and displays the name of the 
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extension and the current state of all LDEF resources. When I see the 
LDEF go bad, Fve gone a long way toward finding the offending code. 

KON During the 7.1 boot process, the system patches are loaded from disk 
and installed. One of those patches opens all the font files in that crazy 
font folder. After all the patches are installed, the system extensions 
arc loaded, starting with the 8*24 GC card. It’s loaded first so that 
QuickDraw is in a well-defined state before other system extensions go 
and patch out the world; once third parties start getting in there, it’s a 
free-for-all. 


25 


20 


15 


BAL Obviously, all the system patches need to be installed before extensions 
are loaded so that the extensions can take advantage of improvements 
provided by the patches. Haven’t you ever wondered why booting 
takes so long? 

KON While the font files are being opened, the resource map is fine. But 
just before the first extension is loaded, the resource map is bad. 

BAD We need to narrow down where the map is going bad. Ell look 

through the system map for the ID that’s getting stepped on. First I 
get the size of the resource map handle by using 

wh @@sysmaphndl 

Then I can find the resource ID with 
f @@sysmaphndl size f060 

since F060 is hex for -4000, the resource ID that’s getting smashed. 
KON Good try, but you find seven occurrences, 

BAL So I continue until the map goes bad, and check for -4000 again. I’ll 
find the one that’s changed, reboot, and step-spy on that address. 
Ta-da! 

KON Sorry, but the resource map is a handle and it has moved on you. You 
can identify the one that’s changed, but you can’t step-spy on it since 
it’s moving around all the time, 

BAL Fine. I’ll reboot in 24-bit mode, lock the handle down by setting the 
high bit of the resource map handle’s master pointer, and step-spy on 
the address. Over, 


10 KON Now Standard File works fine, but file sharing is starting to act flaky. 

BAL OK, So Fm going to have to brute force it. I’ll break when the last 

font loads. I’ll log the MaesBug output to a file with log myLDEFFile 
and then atb ";rd LDEF;g to break on all traps and dump all the 
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25-45 You're spending too much time playing with that 3DO interactive multiplayer machine at 
your local electronics store. 

5-20 You're spending too much time at the gym." 
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5 


LDEF resources* HI also do an ate hopenresfile and then an atb 
hopenresfile to clear the rd LDEF;g when HOpenResFile Is hit* This 
way we'll fall into MacsBug when the first INIT is opened. Then I’ll 
let it rip and get some lunch. 

KON Pretty snazzy there, RAL. Before the map goes bad you see a bunch of 
Slot Manager calls and control calls* The last trap that gets called 
before the map goes bad is a control call to the driver which seems to 
originate from within ImtGDevice. 

BAL Hmmm. We're at secondary INIT time. The driver gets called again 
since all die system patches are now loaded. We added this because 
monitors boot back to the same configuration they were in when the 
machine was shut down. With 32-Bit QuickDraw, the machine 
could have been shut down in 32-bit video mode, so the driver needs 
to be called a second time after the system patches (where 32-Bit 
QuickDraw lives) are loaded, 

KON Yeah, the call t hat's killing the map is a call to the driver to set the bit 
depth. At secondary INIT time the ’scrti' resource is read to find out 
what the last bit depth was, and each device is called to set the depth 
up properly. 

BAL The call must he going to the bogus Kong video card Fung gave you. 
What's the ROM version on that thing? 

KON It's a beta ROM, When 1 asked Mike Puckett about it he said there was 
some nasty “fungus” in the code, and that it was fixed before final. He 
gave me a new video ROM, and now everything works great. Real- 
world users would never experience this, of course, since the problem 
was corrected long before the card went out. 

BAL You and Van Brink should share pack rat stories. You never know, some 
of that old equipment might become collector’s items some day. 

KON This problem began when I started using MacArlas because I switched 
my Kong into grayscale mode. My system is a lot more stable now that 
those spurious writes have been fixed. Before 1 tracked this bug down, 

1 was having intermittent problems. 

BAL Nasty. 

KON Yeah. 
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Thanks ro Peter Hoddie, Brian McGbie, and 
Mike Puckett for reviewing this column." 
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HISTORY OF 
THE DOGCOW 

PART 1 


I’m going to tell you a few things that have never been 
put in prim before about the dogcow. If you don’t know 
what or who the dogcow' is, or you don’t care for Apple 
cultural minutiae, you should just flip past this column. 

This is only part 1 of the story, to be followed by more 
in a future issue of develop , We didn't want to hit you 
with it all at once, for fear of what the shock (or the 
boredom) might do, 

HOW IT ALL BEGAN 

The dogcow was originally a character in the Cairo 
font that used to ship with the Macintosh; it was 
designed by Susan Kare, 1 had always been interested in 
this critter ever since 1 first saw r it in the LaserWriter 
Page Setup Options dialog, sometime during my stint 
in Apple’s Developer Technical Support (DTS) group 
in 1987, lb me it showed perfection in human interface 
design. With one picture it was very easy to explain 
concepts like an inverted image or larger print area that 
otherwise would be nearly impossible to communicate. 

Interest became an obsession when one day I was 
talking to Scott (“Zz'') Zimmerman about the dialog 
and suddenly thought, “Just what is that animal 
supposed to be, anyway?” Since Zz was the Printing 
Guy in DTS (now in the Newton group), and my 
favorite pastime was to bother him endlessly anyway, I 
started pressing him on whether the animal was a dog 
or a cow. 



MARK ("THE RED") 
HARLAN 


In an act of desperation he said, “It's both, OK? It’s 
called a ‘dogcow.’ Now will you get out of my office?” 
The dare was October 15, 1987, and I consider this to 
be the first use of the term. It should be noted that 
since then a few people (including Ginger herself) have 
told me that actually the phrase was coined by Ginger 
Jernigan (ex-DTS, now ROM software) at a meeting of 
Apple's Print Shop sometime shortly before that, which 
very well could be the case. Nevertheless it w r as Zz who 
pressed it into common usage, and he certainly was the 
first person I ever heard use the term. 

Zz’s ploy to get me out of his office was futile, how ever, 
because then I Stood around and postulated that the 
dogcow's genes would have a radical effect on its 
behavior, and it must not bark or moo, but rather utter 
a combination like “Boo-woo!” or “Moof!” 

We both thought it w r as funny enough that we decided 
to press it into everyday usage, and I started circulating 
the dogcow with “Moof!” on internal memos. The idea 
caught on, and at the 1988 Worldwide Developers 
Conference we gave away dogcow buttons in ihe 
debugging lab. Loud la Pizzuti (ex-DTS, ex-develop 
editor, now citizen of the world) came up with the great 
idea of making the background Mountain Dew green. 
Response to the buttons w f as huge, and no one was 
smiling more than the DTS folks when John Sculley 
wore one for lus keynote speech. It was a major-league 
coup. 

THE ORIGIN OF TECH NOTE #31 

Then things started to spin out of control. Various 
groups internally started picking up the dogcow logo 
and doing things that didn’t seem, well, DTS-like. The 
final straw was when the dogcow pin appeared in a 
Microsoft advertisement, Markjohnson (ex-DTS, now 
in Apple Europe) approached me and suggested that we 
throw r down the gauntlet and w r rite a Technical Note on 
the subject. I balked out of nothing more than sheer 
laziness. 

Some time passed and we were getting ready to go w r ith 
die April 1989 batch of Tech Notes when Mark 
approached me again, saying that he thought having an 


MARK ("THE RED") HARLAN started life in Rawlins, Wyoming, 
and has led about exactly the kind of life you'd expect as a result. 
He spends most of his time at Apple finding employees who were 
hired by Steve Jobs and asking them, "So how does it feel knowing 
that the way you changed the world is by putting Windows on all 
PCs?"* 


Our friend in the LaserWriter Page Setup Options 
dialog, normal and with Invert Image and Larger Prinl Area 

7==k 

M 
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April Fool’s edition describing the dogcow would be 
perfect. I said yes but then stalled and stalled, missing 
two deadlines, and I thought the Tech Note wasn’t 
going to happen. 

Mark marched in my office one day in March of 1989 
at 1 1 ;30 a.m. announcing that Tech Notes were 
shipping at noon and implied that my manliness was in 
question if I didn’t get that Note in die batch. My 
macho instincts just couldn’t allow drat to happen, so 
Tech Note #31, “The Dogcow,” was written in literally 
40 minutes in one pass. I’d been thinking about it for 
quite some time, so I knew r pretty much how it would 
go; 1 just sat down and typed it out. Given more time I 
definitely would have churned out something a bit 
more polished, and part of its quirkiness, I’m sure, is 
due to die time pressure I was under. 

One thing was certain: it had to be something original 
in concept. IVe always had a deep disdain for people 
who rip off comedic stuff. You know, the same people 
who used to have to tell all their jokes with an English 
accent because of Monty Python are now those who say 
“Not!” behind phrases. Once is funny, hut after a while 
it gets really old. I definitely wanted it out of the 
mainstream. 

For numbering I wanted to use e, but Mark pointed out 
that there had been confusion early on in the Tech 
Note numbering scheme and that a few numbers had 
been left out For various reasons. Me showed me some 
conversations from the net that went on and on about 
Tech Note #31 and people’s guesses as to why it was 
missing. (People were really, really out there with their 
guessing; anyone who’s a believer in conspiracy theories 
would have enjoyed this blatant gibberish.) The 
number 31 had the right fed: it would blend into the 
regular batch better than e, and Pve always had a soft 
spot for prime numbers, so we picked it. 

Spans Illustrated had run a great fake story about a Zen 
baseball pitcher sometime earlier and we borrowed the 
idea of having the words “April Fool’s” spelled out 
within the article from them — in our case using the 
first letter of every line of the poem at the closing. No 


one has ever mentioned this to me, so few people must 
have caught it. 

There’s a picture of the wrong way to draw the dogcow 
that several people thought was a scanned image ofZz. 
Actually, completely independently of the Tech Note, 
I’d been using a program called Mac-a-Mug, designed 
to make mug shots, and came across a set of hair that 
looked frighteningly like Zz’s. After fiddling around 
with the program a hit I was able to come up with a 
good rendition of Zz’s head, and I shoved it into die 
Tech Note without his ever knowing about it. The 
expression (and color) of his face when he learned 
about the picture is a memory I’ll always cherish. 

The Note also contains the expression “Aanal, Enacku 
Naiimadu, Kaanalil” People came up with very unusual 
anagrams or unusual explanations tor what it meant, 
the best being that it was an obscure reference to a clip 
of The Day the Eunh Stood Still that had been cut from 
the film. But the truth is that it’s phoneticized Tamil 
that was supplied bv Sriram Subramanian (Networking 
Guv, ex-DTS, ex-Taligent, now in Apple Japan) 
meaning “But I can’t see the dogcow!” 

Ironically, there’s also a mistake in that the “correct” 
way to draw the dogcow is actually wrong. We ended 
up being so pressured for time in getting the Note out 
the door that we just jammed it into a weird PostScript 
file that ended up mutating the shape. Shortly after the 
release of that Note, Chris Derossi (ex-DTS, now at 
General Magic) convinced me that a better solution 
was to have the correct way to draw the dogcow be 
pixel a ted, to avoid these idiosyncracies in the future — 
which is what’s now done. 

NEXT TIME 

There will be more history of the dogcow in a future 
issue of develop. I lave you ever wondered if you have 
the entire set of dogcow pins? Is that dogcow T-shirt of 
your cubemate’s bootlegged? Is there any way things 
can get more meaningless? Some, but not all, of these 
questions will be answered the next time we have a 
little extra space to fill. 


Tech Note #31 is not on this issue's CD and hasn't been on Thanks to Gary Robinson, whose letter asking for the story of the 

the CD for quite some time now; it's no longer available. It used to dogcow inspired this column.* 

be hidden in the Technical Notes Stack on the early versions of 

develop 's CD. It appeared on paper only once, as part of the 

monthly mailing to Apple Partners and Associates in April of 1989. 

The continued secrecy has a little bit to do with history and a lot to 
do with tradition. For more on the distribution of the Tech Note, 
stay tuned For History of the Dogcow: Part 2.* 
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WANT TO 
WRITE FOR 
develop? 


We're always looking for people who might be interested in writing an 
article or a column for develop. If you W like to take advantage of this 
opportunity to spotlight and distribute your code to thousands of 
developers of Apple products, with a result that you'll he proud to show 
your colleagues (and Mom), please read on. 



YOUR NAME HERE 


WHAT TO WRITE 

Think about writing an article like the ones you see in this issue, usually ranging 
from 6 to 30 pages in length, or just a short column (say, 2 to 4 pages). Typically 
you’ll expound on source code that readers will get on the CD, 

We encourage authors to write in a light, humorous style; well cry to refrain from 
editing out your jokes! 

WHO AND WHAT CAN HELP YOU 

A content editor and technical editor will work with you on your article, and an 
illustrator will work on any illustrations, A review 1 hoard w ill give feedback on your 
first draft, and numerous technical reviewers will look for errors. Once things come 
together in the final draft, a copyeditor will go over it all. 


Not only will you have an opportunity to review your article at several stages, we 
rely on you to answer questions and in general to review all changes carefully 


WHAT TO DO NEXT 

Ask for our Author’s Guidelines, which include information about timing and the 
scoop on our incentive program. Mail your request to DEVELOP on Apple!.ink, 
develop@applelink.apple.com on the Internet, or Caroline Rose, Apple Computer, 
Inc., 20525 Mariani Avenue, M/S 303-4DP, Cupertino, CA 95014, 

Don’t just sit on those great ideas; feel the thrill of seeing them published in develop\ 


YOUR bio here (modes! or otherwise). 


Thanks for your interest We look Forward 
to hearing From you.* 










HOW / RE WE DOING? If you have any questions, suggestions, or even gripes about develop, please don't 
keep them to yourself. (Be sure to include your name, company name, address, and p>hone number.) 


Send editorial suggestions or 
comments to AppleLink DEVELOP 
or to: 

Caroline Rose 

Apple Computer, Inc- 

20525 Mariani Avenue, M/S 3Q3-4DP 

Cupertino, CA 95014 

AppleLink: CROSE 

I n te rn et: crose @a ppl e link, app 1 e, com 

Fax: (408)253-8521 


Send technical questions 
about develop to: 

DaveJohnson 
Apple Computer, Inc, 

20525 Mariani Avenue, M/S 303-4DP 
Cupertino, CA 95014 
AppleLink: JOHNS ON. DK 
Internet: dkj@apple.com 
CompuServe: 75300,715 
Fax: (408)253-8521 


WANT TO SUBSCRIBE? CHANGE OF ADDRESS? SUBSCRIPTION QUERIES? 

For all your subscription-related needs, see the subscription card, or send a message to DEV SUBS on AppleLink 
or devsubs@appldink-apple.com on the Internet. 

WANT TO WRITE FOR develop ? If you’d like to contribute an article or column to develop, please see 
the blurb on die reverse of this page. 


BACK ISSUES OF develop are on the develop Bookmark CD and on the Developer CD Series disc. To get 
printed back issues, send $13 per issue in the U.S, (or $20 outside the U.S.) to the address on the subscription card. 


Issue 1 Color; Palette Manager; Offscreen Worlds; 
PostScript; System 7 Compatibility; Debugging 
Declaration ROMs; Apple 11 Development Dynamo 

Issue 2 C++ Objects; Object Pascal; Memory 
Manager; MacApp; How to Design an Object-Based 
Application; C++ Style Guide; The GS/OS Cache 

Issue 3 ISO 9660 and High Sierra; A Mixed-Partition 
CD; Accessing CD Audio Tracks; Comm Toolbox; 
Macintosh Display Card 8*24 c;c; PrGeneral 

Issue 4 Device Driver in C++; Polymorphism in C++; 
A/ROSE; PostScript; Apple lies Printer Driver 

issue 5 [Volume 2, Issue 1) Asynchronous Background 
Networking; Scanning From ProDOS; Palette 
Manager Animation; Macintosh Common Lisp 

Issue 6 Threads; CopyBits; MacTGP Cookbook; 
Constructing Network-Aware Applications 

Issue 7 QuickTime 1.0; TrueType; Threads and 
Futures; C++ Objects in a World of Exceptions 

Issue 8 Curves in QuickDraw; Validating Date and 
Time Entry in MacApp; Debugging; Hybrid 
Applications for A/UX 

Issue 9 Color on 1 -Bit Devices; The TextBox You’ve 
Always Wanted; Making Your Macintosh Sound Like 


an Echo Box; Simple Text Windows via the Terminal 
Manager; Tracks: A New Tool for Debugging Drivers 

Issue 10 Apple Event Objects; PostScript 
Enhancements for the LaserWriter Font Utility; 
Drawing in GWorlds; The Optimal Palette 

Issue 11 Asynchronous Sound; Multi buffering 
Sounds; Exceptions; NetWork: Distributed Computing 

Issue 12 Writing and Debugging Components; Time 
Bases: The Heartbeat of QuickTime; Apple Event 
Coding Through Objects; Giobals in Standalone Code 

Issue 13 Asynchronous Routines; QuickTime and 
Component-Based Managers; Macintosh Debugging 
Revisited; Adventures in Color Printing; Device Loop 

Issue 14 Writing Local!zahle Applications; 3-D 
Rotation Using a 2-D Input Device; Video Digitizing 
Under QuickTime; Making Better QuickTime Movies 

Issue 15 Getting Started With QuickDraw GX; 
QuickDraw GX Printing Extensions; QuickDraw GX 
for PostScript Programmers; Component Registration; 
Floating Windows; Working in the Third Dimension 

Issue 16 Making the Leap to PowerPC; PowerTalk; 
Drag and Drop From the Finder; Color Matching 
Made Easy With QuickDraw GX; International 
Number Formatting 







RESOURCES 


Apple provides a wealth of information, 
products, and services to assist 
developers. A PDA, Apple's source for 
developer tools, and Apple Developer 
University are open to anyone who 
wants access to development tools and 
instruction. Developers may access 
additional information and services 
through Apple's Developer Programs. 

APDA offers convenient worldwide 
access to development tools, 
resources, training products, and 
information for anyone interested in 
developing applications on Apple 
platforms. Customers receive the 
quarterly APDA Tools Catalog 
featuring over 200 Apple and third- 
party development products. There 
are no membership fees. APDA 
offers convenient payment and 
shipping options, including site 
licensing. 

Apple Developer University (DU) 
provides software development 
courses designed to increase your 
development productivity The 
curriculum includes courses to get 


APDA To order products or to receive a 
complimentary catalog, call 1-800-282- 
2732 in the US„ 1-800*637-0029 in 
Canada, (716)871-6555 internationally, or 
(716)871 -651 1 lor fax. You can also order 
electronically (AppleLink APDA; Internet 
APDA@applel!nk r app3e,com; CompuServe 
76666,2405; or America Online APDA) or 
write APDA, Apple Computer, lnc v P.O. Box 
319, Buffalo, NY 14207-0319. 


you started programming on Apple 
platforms, as well as advanced, in- 
depth training on the newest xApple 
technologies, such as PowerPC, 
AOCE, QuickDraw GX, and 
Newton. DU offers courses in 
Cupertino CA and at selected 
training locations. The DU 
Extension partners located in Plano 
TX and Portsmouth NH also 
s ehe d u I e set ecte d courses in th e i r 
facilities. In addition to classroom 
training, DU offers multimedia self- 
paced courses and low-cost mini- 
course tutorials. 

The Associates Program is Apple's 
primary program for developers 
across all Apple technologies, 
including Macintosh, Personal 
Interactive Electronics (such as 
Newton), and multimedia. IPs a 
low-cost, self-support program that 
also provides a connection with 
Apple and fellow developers, 
information on new technologies, 
and discounts on equipment. 

The Apple Multimedia Program 

is designed for developers interested 
in the emerging multimedia market. 
Program features include a quarterly 
mailing and discounts on third-party 
products, training, and events. 


Apple Developer University The 

registrar at (408)974-4897 can reserve 
your place or send a current Curriculum 
Guide and Course Schedule. You can also 
send an AppleLink to DEVUNEV or write 
Developer University, Apple Computer, 3nc. r 
20525 Mariant Avenue, M/S 305-1TU, 
Cupertino, CA 95014. Self-paced products 
should be ordered directly through APDA, 


The Macintosh Technology 
Partners Program is open to 
Apple-selected strategic developers 
focused on Macintosh technology, 
including PowerPC, QuickTime, 
QuickDraw GX, and Power Talk. In 
addition to receiving the same 
development information and tools 
as members of the Associates 
Program, Macintosh Technology 
Partners receive programming-level 
development support via electronic 
mail. Membership in this program is 
limited to strategic developers who 
directly contribute to Apple's long¬ 
term product plans and business 
objectives. 

The PIE Partners Program is 

open to Apple-selected strategic 
developers focused on Personal 
Interactive Electronics. It offers the 
same core features as the Associates 
Program, hut also includes 
programming-level development 
support via electronic mail, 
additional hardware purchasing 
privileges, marketing programs, and 
media production assistance. 


Apple Developer Programs Call the 
Developer Support Center at (408)974- 
4897, AppleLink DEVSUPPORT, or write 
20525 Mariani Avenue, M/S 303-2T, 
Cupertino, CA 95014, for information or an 
application form. Developers outside the UA 
and Canada should instead contact the 
Apple office in their country for information 
about developer programs. 








Q 


2 


<c < ^ 

1 M CO 
U, W CO 

rt w ■” 

<1 o 

3 g 

2 211 

. o 0) 
- 1 


$10.00 

1047-0735 

© 

Printed on recycled paper 


Apple Computer, Inc. 
20525 Mariani Avenue 
Cupertino, CA 95014 













